ShellFolder Class

Properties   Methods   Events   Config Settings   Errors  

The ShellFolder class enables creating a virtual folder containing items in the Windows Shell.

Syntax

class cbfsshell.ShellFolder

Remarks

The ShellFolder class provides a simple way to create a virtual folder in the Windows Shell. The class enables control over the folder contents, customizing columns within the virtual folder, managing individual item properties, and more.

The class communicates with the Windows Shell through a proxy DLL that is loaded by Explorer in order to provide a custom region in the Windows Shell namespace. The set of modules included in this product is discussed in the Deployment Instructions.

Installation and Initialization

Set display_name and location to the desired values and call install to register the proxy DLL with the Windows Shell.

Installation should be done at least once before using the library on a new system, but may be done several times to update the values of the properties attributes, display_name, icon_location, location, proxy_path, and scope.

In most cases, it is necessary to restart Windows File Explorer after installation to refresh the list of namespaces. The Windows File Explorer view option "Launch folder windows as a separate process" will run new shell views in a different process, scanning for extensions; when the option is enabled, it is not necessary to restart Windows File Explorer but you need to open a new Shell folder to see a newly installed virtual folder.

ShellFolder component = new ShellFolder(); component.DisplayName = "Sales Department"; component.Location = Constants.NS_LOCATION_DESKTOP; component.Install();

After installation, the root folder will be visible in Windows File Explorer but it will not be ready to handle user interation.

The next step is to call initialize, which will perform the necessary operations to facilitate communication between the system and your code. Initialization only needs to be called once per application launch.

component.Initialize();

Activate

The application should call the activate method to turn on the virtual folder. Folder events will fire that correspond to Windows Shell tasks that need to be handled. Some events are mandatory, while others are fired only when certain functionality is enabled.

component.Activate();

Items

Handle the on_list_items event to add items to Windows File Explorer view. Call list_item for each folder or non-folder item. This event will fire every time a folder identified by ParentId needs to be listed. Your code should make sure that list_item method is called only when an item should be visible as a subitem of ParentId. Retrieving the data to represent is up to you, and how to fetch the data usually depends on the data source.

private void OnListItems(object sender, ShellFolderListItemsEventArgs e) { // Add a file item var itemId = "0"; // Use your own logic to identify, name, and describe the item var path = ""; // Set this to a path of a real file if desired var name = "MyItem.txt"; var size = 1000; var iconPath = ""; var iconIndex = 0; var attributes = Constants.SFGAO_HASPROPSHEET | Constants.SFGAO_STORAGE | Constants.SFGAO_STREAM; m_Folder.ListItem(e.TaskId, itemId, attributes, size, name, path, iconPath, iconIndex); // Add a folder item itemId = "1"; name = "MyFolder"; attributes = Constants.SFGAO_FOLDER | Constants.SFGAO_HASPROPSHEET | Constants.SFGAO_STORAGE | Constants.SFGAO_STREAM; m_Folder.ListItem(e.TaskId, itemId, attributes, size, name, path, iconPath, iconIndex); }

After the on_list_items event returns, the folder will be populated with the listed items, and they will be accessible within Windows File Explorer.

Note: The items should be uniquely identified by your code, setting the ItemId parameter of the list_item call. It is important to choose an identifier that makes sense to you, as the same identifier will be presented when subsequent operations are performed against your new item. Please see Shell Item Ids for more information.

Properties

Properties are name-value pairs that express metadata about the items. Handle the on_get_properties event to store details for your items. Applications should call add_property for each property value that should be associated with a particular item. This event will fire together with on_list_items to get property values for each item. The specified properties will be shown within Windows File Explorer and retrieved automatically without any additional steps required.

private void OnGetProperties(object sender, ShellFolderGetPropertiesEventArgs e) { var propertyId = 4; // An identifier for System.Author defined by MSFT var formatGUID = "{F29F85E0-4FF9-1068-AB91-08002B27B3D9}" var propertyType = Constants.PROP_TYPE_STRING; var numericValue = 0; // Set only for numeric properties var dateValue = DateTime.MinValue; // Set only for date properties var stringValue = "John Doe"; // Set only for string properties // Add an Author property to the item m_Folder.AddProperty(e.TaskId, formatGUID, propertyId, propertyType, numericValue, dateValue, stringValue); }

Note: Properties are displayed in the Properties dialog box for a folder or an item, or in additional columns when Windows File Explorer is set to the Details view mode. Choose from the existing list of Windows Properties or register your own property with the system by calling register_schema once per application installation. Please see Property System for more details.

Columns

The class allows customizing columns in Windows File Explorer view. Handle the on_get_columns event, and if the given folder should have columns, call add_column once for each column. Your code should make sure that add_column is called only when a particular column should be added to the folder identified by ParentId. Your code should also ensure that one column is added for each custom property.

private void OnGetColumns(object sender, ShellFolderGetColumnsEventArgs e) { var propertyID = 4; // System.Author var formatGUID = "{F29F85E0-4FF9-1068-AB91-08002B27B3D9}"; var flags = Constants.SHCOLSTATE_ONBYDEFAULT; var name = ""; // Set only if using a dynamic column var defaultWidth = 0; // Set only if using a dynamic column var viewFlags = 0; // Set only if using a dynamic column // Add an Author column to the folder m_Folder.AddColumn(e.TaskId, formatGUID, propertyID, flags, name, defaultWidth, viewFlags); }

After the add_column method is called, the property values that correspond to the newly added column will be visible in Windows File Explorer.

Note: Columns are linked either to predefined properties or properties that have been registered with the system by calling register_schema once per application installation. Columns linked to custom properties are referred to as dynamic columns and are limited in their capabilities. Please see add_column for more information.

Item Information

The application should handle the on_get_item_id and on_get_item_info events to provide the class with details about the items. These events are triggered when the system needs data which may be specific to your usage scenario. For example, the identifiers associated with each item are known only to your code.

private static void OnGetItemId(object sender, ShellFolderGetItemIdEventArgs e) { var displayName = e.DisplayName; // Get the item that should be identified e.ItemId = itemId; // Use your own logic to set the ItemId }

The class will occasionally search for items and retrieve other data associated with the item separate from the identifier. This is done for caching reasons and to ensure that the system is updated with all the information it needs.

private void OnGetItemInfo(object sender, ShellFolderGetItemInfoEventArgs e) { var itemId = e.ItemId; // Get the item that should be described e.Size = size; // Use your own logic to set item information e.IconIndex = iconIndex; e.IconPath = iconPath; e.FileSystemPath = fileSystemPath; e.Attributes = attributes; e.DisplayName = displayName; }

Item Content

The class will handle returning the contents of a file when the item is physical, meaning it contains a value in the FileSystemPath parameter to the list_item method. No other steps are required in this case.

If no value is provided in FileSystemPath parameter, the class will trigger the on_get_item_data event when the Windows Shell requests the contents of a non-folder item. An application should handle this event to return data to applications that read from the file identified by ItemId. private void OnGetItemData(object sender, ShellFolderGetItemDataEventArgs e) { // Return item content Array.Copy(content, e.Buffer, size); }

Please see Physical and Virtual Windows Shell Items for more information.

Deactivation and Uninstall

To stop handling requests, call the deactivate method. Deactivation should be done when the application ceases to process requests from the Windows Shell, rendering the virtual folder inactive.

component.Deactivate();

To unregister the proxy DLL from the system, call the uninstall method. This action removes the virtual folder and is usually performed during an application's uninstall routine.

component.Uninstall();

Physical and Virtual Windows Shell Items

ShellFolder supports two types of virtual Windows Shell items (both folders and non-folder items). Physical items are associated with files and directories on some drive and have a corresponding path within a filesystem. Virtual items are not associated with a filesystem path. Both virtual and physical items may exist in the same Windows Shell folder.

Physical Items and Folders

Physical items and folders are associated with a physical filesystem path (file or folder). When working with physical items:

• The FileSystemPath parameter of the list_item method must be set to a non-empty value that is a valid path to an existing file or directory. The class does not validate the path, but using an invalid path may lead to unexpected side effects when such an item is used.
• Many properties will be automatically computed from the associated physical file or directory.
• File content can be modified.
• Physical items benefit from better automatic Windows Shell integration. For instance, many third-party context menu handlers will add menu items to Windows Shell items that are backed by a physical file.
• Physical items benefit from better usability with custom applications (e.g., Office, Notepad).

Note: When an application opens a physical item in your namespace, the user may want to save a file under a new name. The Shell then offers the filesystem directory that is a parent of a backing file as a default location for a Save As operation. If the data is then saved to that directory, the namespace extension does not get notified about creation of such a file (the writing of the data occurs on the filesystem level rather than via the Shell). If a namespace extension needs to know about such save operations, it may use the ShellNotify class to monitor the directories that are exposed via the extension.

Physical Shell Items Options

The SFGAO flags associated with the physical items or folders will determine the behavior of the Shell in regard to these items. The flags for physical items are provided in the list_item method, and the default flags are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_FILESYSTEM

The default flags for physical folders are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_BROWSABLE
• SFGAO_FOLDER
• SFGAO_FILESYSTEM
• SFGAO_HASSUBFOLDER

Virtual Items and Folders

Virtual items and folders are not associated with a physical path, and the item is completely virtual. When working with virtual items:

• The FileSystemPath parameter of the list_item method must be set to empty string.
• Additional handling may be necessary (such as handling of the on_get_item_data event for files).
• Item content cannot be modified. For instance a user will be able to open a virtual Excel "file", but will not be able to save changes to the same file.
• Virtual items can support custom filenames including characters which are typically forbidden (e.g., < > :). This support can be helpful when displaying items from an external source.
• All aspects of a virtual Windows Shell item, such as visibility, content, and properties, may vary according to the context (user account, time of day, language, etc.). For example, the same virtual PDF file with the exact same name may be displayed to all users, but the content of the file may differ each time a user opens it.

Virtual Shell Items Options

The SFGAO flags associated with virtual items or folders will determine the behavior of the Shell in regard to these items. The flags for virtual items are provided in the list_item method, and the default flags are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM

The default flags for virtual folders are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_BROWSABLE
• SFGAO_FOLDER
• SFGAO_HASSUBFOLDER

Shell Item Ids

When a folder's contents are requested, the on_list_items event fires. If a folder is not empty, a handler of this event should make one or more calls to the list_item method to provide information about each item within the folder. When calling list_item, the Id parameter must be set to a unique identifier. The process used to generate the Id value is outside the scope of the class, but it is recommended that the Id be no longer than 64 characters and be comprised of alphanumeric characters.

The Id of the item should not change once it has been specified. When the directory is enumerated again, the same Id should be returned for the item. Additionally, the Id should not change across user sessions. If a shortcut to an item is created by the user, and that item's Id changes, the shortcut will become invalid.

The Id specified in the call to list_item will be provided as a parameter in other events that fire when the item is accessed.

PIDLs

A PIDL (or an IDL) is a fundamental Windows Shell concept. At a high level, it is pretty simple, as it is just a value that represents a Windows Shell item in the Windows Shell Namespace. It is a bit like a full filesystem path for a physical file or folder, except that it is a binary object and not a string. The name "PIDL" and "IDL" can be used interchangeably. The leading P stands for pointer, the IDL stands for item identifier list, and PIDL generally refers to an IDL itself rather than the pointer to it.

The below information is provided as a general knowledge. Your application will deal with PIDLs only when they denote some Windows Shell items that are not necessarily a part of the Windows Shell namespace extension that you create. Such PIDLs can be used with the Windows Shell API if you decide to call it directly. When CBFS Shell exposes these PIDL values they will appear hex-encoded. If an application needs to call a shell function, it has to decode the PIDL before calling that function.

Just like a full filesystem path is a list of strings separated by the directory separator (on Windows, it is the \ (backslash) character), a PIDL is a list (L is for list) of Ids (identifiers). Unlike a filesystem path, though, a PIDL is binary, and Ids are separated by a special PIDL separator (two consecutive zero bytes).

Microsoft provides more details about PIDLs here Identifying Namespace Objects.

Windows Property System

The Windows property system is used to manage properties of items within the Windows Shell. Properties are used by the add_column and add_icon_column methods to define which property values are present as columns in the Windows Shell. Columns are most often thought of when using the "Details View" in Explorer, however properties are also visible in other views, such as the "Properties" dialog box of an individual item.

A property must be registered in the system before it can be used by add_column or add_icon_column. Many properties are predefined in Windows, however custom properties can also be added by creating a .propdesc file and calling register_schema.

Property Format

Properties have specific characteristics which are used to define and use the property. Each property registered in the system, whether predefined or custom, follows these rules:

• Is uniquely addressed by its PROPERTYKEY, which is a Windows-defined structure (composed of a GUID value and an int32 value).
• Has a canonical human-readable name (e.g., System.ItemNameDisplay).
• Has a schema description, which is specified using the XML format in a .propdesc file and expressed programmatically through the Windows-defined IPropertyDescription interface.

Each column is associated with a property, and by extension is also associated with a "PropertyKey" and its property definition. ShellFolder adds a column for the DisplayName property of all items automatically. Additional columns should be added using add_column and add_icon_column.

Property values

When an item's properties are needed (for instance, during a directory listing), the on_get_properties event fires. The add_property method should be called from within the on_get_properties event hander once for each column to specify the property value for the specified item.

Adding Columns For Properties to a Folder

To add one or more columns that will display property values of items, handle the on_get_columns event and from the event handler, call the add_column or add_icon_column methods.

Properties Defined By Windows

The add_column and add_icon_column methods may be used to add columns using existing predefined properties. Microsoft provides detailed information about Predefined Properties. Note that FormatIDs in Microsoft docs do not include curly brackets, whereas in the property definition schemas and in the code, curly brackets around the GUID must be present.

Custom Properties

To create a custom property, the property must first be defined in a .propdesc XML file. The register_schema method is then used to register the custom property defined in the XML file. The unregister_schema method may be used to unregister a previously registered custom property.

The Microsoft documentation provides additional details on Creating Custom Properties and Understanding the Property Description Schema.

A sample property schema is provided in the next section for reference. Once the .propdesc XML file has been created, it can be registered and unregistered using code like:

// register a property schema from a .propdesc file path MyShellFolder.RegisterSchema("C:\\path\\to\\myproperty.propdesc"); ... // unregister a property schema from a .propdesc file path MyShellFolder.UnregisterSchema("C:\\path\\to\\myproperty.propdesc");

Registering and unregistering of properties requires write access to the HKEY_LOCAL_MACHINE registry hive. It is common to perform registration and unregistration during the installation and uninstallation of an application for this reason.

Sample Property Schema

A sample schema for registering a column with icons is provided below. Please see add_icon_column for additional details.

<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/windows/2006/propertydescription" schemaVersion="1.0" > <propertyDescriptionList publisher="Callback Technologies" product="MyCoolApp"> <propertyDescription name="MyCoolApp.MyIconSource" formatID="{d9f69df5-01ef-4838-acb7-055012a678ca}" propID="4"> <searchInfo reIndexPatterns="" processReIndexPatternsImmediately="true" inInvertedIndex="false" isColumn="false"> </searchInfo> <typeInfo type="UInt32" isInnate="true" groupingRange="Enumerated" isViewable="true"> </typeInfo> <displayInfo displayType="Enumerated"> <enumeratedList> <enum name="None" value="0" text=""> </enum> <enum name="Ok" value="1" text="Ok"> <image res="%systemroot%\system32\imageres.dll,-1405"> </image> </enum> <enum name="Error" value="2" text="Error"> <image res="%systemroot%\system32\imageres.dll,-1402"> </image> </enum> <enum name="Warning" value="3" text="Warning"> <image res="%systemroot%\system32\imageres.dll,-1403"> </image> </enum> </enumeratedList> </displayInfo> <labelInfo label="Icon UI"> </labelInfo> </propertyDescription> <propertyDescription name="MyCoolApp.MyIconUI" formatID="{d9f69df5-01ef-4838-acb7-055012a678ca}" propID="3"> <searchInfo reIndexPatterns="" processReIndexPatternsImmediately="true" inInvertedIndex="false" isColumn="false"> </searchInfo> <typeInfo type="Blob" isInnate="true" isViewable="true"> </typeInfo> <labelInfo label="Icon"> </labelInfo> <displayInfo defaultColumnWidth="10"> <drawControl control="IconList"> </drawControl> </displayInfo> </propertyDescription> </propertyDescriptionList> </schema>

The example schema defines two custom properties:

• MyCoolApp.MyIconUI which is a property of "Blob" type. This property defines a column of the folder view in Details mode.
• MyCoolApp.MyIconSource, which is a property of UInt32 type. It describes which icons can be displayed and where the corresponding images are to be taken from. The example references Windows-provided images, but an application may reference any EXE, DLL, or another PE file with Win32 resources as a source. The syntax of references is the standard Win32 resource syntax, as follows: <path>,-<resource index>

An application may define any number of icon-rendered columns in a folder.

Multiple Root Folders

The class uses a unique Id derived from the license to load a proxy DLL into Windows File Explorer and communicate with the Shell. Each license will allow for one virtual folder to be defined. Please contact support for additional details if multiple simultaneous root folders are required.

Troubleshooting

Following are some helpful resources for troubleshooting issues.

• If you are developing your application and you stop and start repeatedly while keeping Explorer open, there may be a memory/cache issue regarding item icons or names. To avoid this situation, one should terminate all Windows File Explorer processes and restart Explorer.
• If your folder is not visible, check the attributes property. The SFGAO_HIDDEN attribute will hide the extension.
• If your folder is not visible, make sure your folder is not Disallowed. To check this, you can make sure that your folder class Id (see FolderClassGUID) is not found in the below registry key.
  • HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed
  • HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed
  • HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Shell Extensions\Disallowed
• If your folder is not visible, make sure your folder is not Blocked. To check this, you can make sure that your folder class Id (see FolderClassGUID) is not found in the below registry key.
  • HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked
  • HKEY_LOCAL_MACHINE\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Shell Extensions\Blocked
• If your folder is not visible, make sure your folder is Approved. To check this, you can make sure that your project is found in the below registry key.
  • HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved
• If your folder is visible but does not respond to requests, this could be a UAC issue. If your application is running with administrator rights and UAC is disabled, try setting scope to AllUsers before calling install.
• If your folder is visible but does not respond to requests, this could be an incomplete deployment issue. On 64-bit systems, be sure to deploy both the 64-bit and 32-bit native proxy DLL. To ARM systems, be sure to deploy all of the native proxy DLLs.
• If your folder is not visible in Common Dialogs, unfortunately, there may not be a solution to this problem. Common Dialogs are hosted by an application's process and not Windows File Explorer. Each application can customize the dialog any way they want and prevent any folder from appearing.
• If your items are not visible in Common Dialogs, the application may restrict the Common Dialog view to just filesystem items. In this case, your application would need to adapt its code to ensure that the folder and the items contained within the folder contain the attribute SFGAO_FILESYSTEM. Even if your extension is filesystem-compliant, some applications may still fail depending on how they are implemented.
• If your folder is not responding in Common Dialogs, it may be an incomplete deployment issue. Some applications are compiled as 32-bit binaries and use dialogs in 32-bit as well. If the native proxy DLL for 32-bit is not included, the Common Dialog will not be able to reach your folder.
• If you observe slow behavior, it may be that an excessive number of requests are calling your folder. Any third-party extensions or application present on the system can use your extension for various purposes so it is recommended to test on clean and updated systems to narrow down a cause.
• If you observe slow behavior during copy-pasting or drag-n-drop of data (especially, in Microsoft Office applications), it may be the problem of the data source that includes large blocks of data in different formats. You can use various third-party tools to inspect the Clipboard contents or the contents of the dragged data to identify the formats, which contain large blocks of data in which your extension is not interested. Then, you can exclude the undesired formats (or just include the formats you are interested in) using the ExcludeClipboardFormats and IncludeClipboardFormats configuration settings respectively.
• If you are seeing strange behavior not contained in this list, please reach out to us with a description of the problem, and we are happy to help. Our support team is available over email at support@callback.com

Property List

---

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

attributes Property

This property describes various aspects of the topmost virtual folder behavior.

Syntax

def get_attributes() -> int: ...
def set_attributes(value: int) -> None: ...

attributes = property(get_attributes, set_attributes)

Default Value

0xA0C00108

Remarks

This property specifies various options, related to the behavior of the topmost (root) virtual folder, created by the Windows Shell Namespace Extension. Set this property before calling the install method.

The property should contain zero or more of the following flags, OR'd together:

If the root folder is expected to contain filesystem items, add the SFGAO_FILESYSANCESTOR flag to the set of flags.

A more detailed description of the attributes can be found in the dedicated MSDN topic.

The default value of 0xA0C00108 (SFGAO_DEFAULT_ROOT) is a combination of the following flags:

• SFGAO_FOLDER
• SFGAO_HASSUBFOLDER
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_DROPTARGET
• SFGAO_STORAGE

display_name Property

This property specifies the name that the Windows Shell uses when it displays the Namespace Extension.

Syntax

def get_display_name() -> str: ...
def set_display_name(value: str) -> None: ...

display_name = property(get_display_name, set_display_name)

Default Value

""

Remarks

This name is displayed by the Windows Shell and should be human-readable, as end users will recognize your Namespace Extension by this name.

drag_items_count Property

The number of records in the DragItem arrays.

Syntax

def get_drag_items_count() -> int: ...

drag_items_count = property(get_drag_items_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• drag_item_content_path
• drag_item_data
• drag_item_file_name
• drag_item_format
• drag_item_format_name
• drag_item_id
• drag_item_pidl

The array indices start at 0 and end at drag_items_count - 1.

This property is read-only.

drag_item_content_path Property

Contains an absolute name with path of a file with the data item's content.

Syntax

def get_drag_item_content_path(drag_item_index: int) -> str: ...

Default Value

""

Remarks

Contains an absolute name with path of a file with the data item's content.

In some cases, CBFS Shell stores the data in temporary files. In this case, this field contains the path of a temporary file with data, while the FileName field contains the name of the file as set by the data source. When Format is 15 (CF_HDROP), this field contains the same path as FileName.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

drag_item_data Property

Contains the payload of data the item.

Syntax

def get_drag_item_data(drag_item_index: int) -> bytes: ...

Remarks

Contains the payload of data the item.

If the data item contains data payload (rather than a reference to some file or Windows Shell item), such data are accessible via this field. The field may also contain the binary data of a file or Windows Shell item, if the data source provided the data in such a form.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

drag_item_file_name Property

Contains a file name of the data item.

Syntax

def get_drag_item_file_name(drag_item_index: int) -> str: ...

Default Value

""

Remarks

Contains a file name of the data item.

If the data item contains a path to a file or folder or a PIDL of an item or folder that can be resolved to a filesystem path, this field contains the corresponding path.

If the data item carries some data payload with the associated file name, the Data field will be non-empty, and this FileName field will contain the file name associated with the payload.

In other cases, the field is empty.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

drag_item_format Property

Contains the number of the clipboard format.

Syntax

def get_drag_item_format(drag_item_index: int) -> int: ...

Default Value

0

Remarks

Contains the number of the clipboard format.

Data formats, in which data are stored during drag-n-drop and copy/paste operations, have numeric values - either assigned by the system (standard and registered formats) or private, defined by an application from the range dedicated for private formats. This field contains the format, in which the data item is represented.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

drag_item_format_name Property

Contains the name of the clipboard format.

Syntax

def get_drag_item_format_name(drag_item_index: int) -> str: ...

Default Value

""

Remarks

Contains the name of the clipboard format.

This field contains the name or a string identifier of the clipboard format, in which this data item is present. The field may be empty if the format doesn't have a text name/identifier. In such cases, an application should use the Format field with a numeric value of the format.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

drag_item_id Property

Contains an Id of the data item.

Syntax

def get_drag_item_id(drag_item_index: int) -> str: ...

Default Value

""

Remarks

Contains an Id of the data item.

This field contains the Id of the data item. It may be empty if the data item is not a part of the virtual Windows Shell folder or its children.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

drag_item_pidl Property

Contains a PIDL of the data item.

Syntax

def get_drag_item_pidl(drag_item_index: int) -> bytes: ...

Remarks

Contains a PIDL of the data item.

This field contains the PIDL of an item if the data item is a Windows Shell item. If the data item is not a Windows Shell item, such as text or an image, then this property is null.

The drag_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the drag_items_count property.

This property is read-only.

icon_location Property

This property specifies the full path to the file with the icon.

Syntax

def get_icon_location() -> str: ...
def set_icon_location(value: str) -> None: ...

icon_location = property(get_icon_location, set_icon_location)

Default Value

""

Remarks

This property specifies the full path to the file with the icon for the Windows Shell Namespace Extension. Set this before calling the install method to add an icon to the virtual folder.

DLL and EXE Icon Resources

If the icon is contained in an EXE or DLL file, the path may be followed by a comma and an integer value. This may be either an ID or the index of the icon in the resources within the file. If the ID is used, it must be prefixed with a - character. For example:

<path\to\file.dll>,-<resource ID>

<path\to\file.dll>,<resource index>

location Property

This property specifies where the extension is located in the Windows Shell Namespace.

Syntax

def get_location() -> str: ...
def set_location(value: str) -> None: ...

location = property(get_location, set_location)

Default Value

""

Remarks

This property describes where the Windows Shell Namespace Extension will be located in the Windows Shell Namespace. This should be set before calling the install method.

This location must be one of the following specified values:

Additional information about well-known folder IDs can be found in the dedicated MSDN topic.

proxy_path Property

This property specifies the path to the native proxy DLL.

Syntax

def get_proxy_path() -> str: ...
def set_proxy_path(value: str) -> None: ...

proxy_path = property(get_proxy_path, set_proxy_path)

Default Value

""

Remarks

This property may be used to specify the path to the native proxy DLL, which is loaded by the Windows Shell. The value may be in one of these formats:

1. The name of the directory with Proxy DLLs. In this case, the class will choose the first DLL with the appropriate architecture.
2. The full path with the name of the DLL. In this case, just this DLL will be loaded.
3. The full path with wildcards in the name part (a pattern). In this case, the class will choose the first DLL that matches the passed pattern.

If left empty, the class will automatically attempt to locate the appropriate DLL by searching the directory where the application's executable resides.

scope Property

This property specifies whether the class is registered for the current user or for all users.

Syntax

def get_scope() -> int: ...
def set_scope(value: int) -> None: ...

scope = property(get_scope, set_scope)

Default Value

1

Remarks

This property specifies whether the information related to the class is written to the registry for the current user or for all users.

In the latter case, administrative rights are required to successfully execute the install and uninstall methods. If the user account of the process that calls these methods does not have such rights, the call will fail with an error.

selected_items_count Property

The number of records in the SelectedItem arrays.

Syntax

def get_selected_items_count() -> int: ...

selected_items_count = property(get_selected_items_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

• selected_item_file_name
• selected_item_id
• selected_item_pidl

The array indices start at 0 and end at selected_items_count - 1.

This property is read-only.

selected_item_file_name Property

Contains a file name of the selected item.

Syntax

def get_selected_item_file_name(selected_item_index: int) -> str: ...

Default Value

""

Remarks

Contains a file name of the selected item.

If an item is a filesystem object and its PIDL can be resolved to a filesystem path, this field contains a full path on the filesystem; otherwise, the field is empty.

The selected_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the selected_items_count property.

This property is read-only.

selected_item_id Property

Contains an Id of the selected item.

Syntax

def get_selected_item_id(selected_item_index: int) -> str: ...

Default Value

""

Remarks

Contains an Id of the selected item.

If a selected item comes from within the virtual Windows Shell folder managed by the ShellFolder class, this field contans an application-defined Id. In other cases, this field is empty and the application may use the PIDL field to identify the item.

The selected_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the selected_items_count property.

This property is read-only.

selected_item_pidl Property

Contains a PIDL of the selected item.

Syntax

def get_selected_item_pidl(selected_item_index: int) -> bytes: ...

Remarks

Contains a PIDL of the selected item.

This field contains the PIDL of the selected item.

The selected_item_index parameter specifies the index of the item in the array. The size of the array is controlled by the selected_items_count property.

This property is read-only.

activate Method

This method tells the class to start handling the requests sent to the namespace extension.

Syntax

def activate() -> None: ...

Remarks

This method is used to tell the component to begin handling Windows Shell requests and start firing the corresponding events.

add_column Method

This method is used to provide information about a text column during folder enumeration.

Syntax

def add_column(task_id: int, format_id: str, property_id: int, flags: int, name: str, default_width: int, view_flags: int) -> None: ...

Remarks

This method provides the system with information about a text column of the folder referenced in the on_get_columns event. This method should only be called from within the on_get_columns event handler. To add an icon column, use add_icon_column instead.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the on_get_columns event.

The FormatId parameter specifies the GUID of the property format. This acts as a broad identifier for a set of related properties and their corresponding columns. Its value must be specified in Registry Format. For instance: {1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}.

The PropertyId parameter specifies the ID of the property. Its value is used to identify each property distinctly in a group that shares the same GUID.

The Flags parameter configures the behavior and display settings of the column. Its value may include one or more of the following SHCOLSTATE flags OR'd together. Note that some of these flags are only applicable to dynamic columns:

The Name parameter specifies the visible text that identifies the column in Windows File Explorer. This value should be set to an empty string when adding columns for custom properties registered with the register_schema method.

The DefaultWidth parameter determines the starting size of the column in Windows File Explorer.

The ViewFlags parameter is used to describe the column presentation and behavior of dynamic columns. This should be set to 0 when adding a column for a property that has been registered with register_schema. Its value can have zero or more of the following flags OR'd together:

Dynamic Columns

Columns for custom properties that have not been registered with register_schema are referred to as dynamic columns. Unlike columns that correspond to registered properties, dynamic columns are limited in their capabilities and do not carry any definition, schema, search information, or display information. The type of data they carry, along with their name, width, and visual properties, can only be specified by doing the following:

• Provide a non-empty string in the Name parameter
• Specify the default width of the column using DefaultWidth
• Set the type of the data displayed in the column using the corresponding flag in the Flags parameter
• Specify the column presentation and behavior using the ViewFlags parameter

add_icon_column Method

This method is used to provide information about a column of a folder with an icon during folder enumeration.

Syntax

def add_icon_column(task_id: int, icon_source_property: str, icon_ui_property: str) -> None: ...

Remarks

This method provides the system with information about an icon column of the folder referenced in the on_get_columns event. This method should only be called from within the on_get_columns event handler. To add a text column, use add_column instead.

Before a column for icons can be added to a folder, a set of two properties must be registered in the Property System using the register_schema method. The first property describes the set of icons the column can display, each associated with a numeric value. These values act as identifiers for the icons and can be used to specify the icon that will be displayed for a particular column by using the add_property method. It is important to note that an icon column is limited to displaying icons from this predefined set.

The second property describes the visual aspects of the column, such as its name and default width. For an example of how these two properties are defined, see the sample property schema Property System topic in the introduction section.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the on_get_columns event.

The IconSourceProperty parameter should be set to the value of the "name" attribute in the "propertyDescription" tag of the property that describes the set of icons the column can display. In the sample schema from the Property System topic, this value corresponds to MyCoolApp.MyIconSource.

The IconUIProperty parameter should be set to the value of the "name" attribute in the "propertyDescription" tag of the property that describes the visual aspects of the column. In the sample schema from the Property System topic, this value corresponds to MyCoolApp.MyIconUI.

add_menu_item Method

This method is used to add a menu item to a context menu.

Syntax

def add_menu_item(task_id: int, verb: str, parent_verb: str, caption: str, is_default: bool, is_enabled: bool) -> None: ...

Remarks

This method provides information to the system about a menu item to be appended to the context menu. This method should only be called from within the on_merge_menu, on_merge_menu_top, and on_merge_menu_bottom event handlers.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the corresponding event.

The Verb parameter specifies the unique text identifier of the menu item. This is the value that identifies menu items in the on_invoke_menu event.

The ParentVerb parameter is used to create submenus. If set to the verb of a menu item previously added with the add_menu_item method, the new item will be added as a child under that item's submenu. Otherwise if ParentVerb is set to an empty string, the new menu item will appear at the top level of the context menu.

The Caption parameter is the visible text that represents the menu item in the context menu.

The IsDefault parameter marks the menu item as default. When set to true, the menu item will be invoked when a user double-clicks on an item in the virtual folder. Only one menu item can be marked as default in the context menu.

The IsEnabled parameter specifies the selectable state of a menu item. When set to true, the menu item will be active and selectable in the context menu. If set to false, the item will be unselectable and appear greyed-out in the context menu.

Naming Verbs

When naming verbs, it is recommended to use unique names to avoid collisions with other applications. Generic verb names such as open or edit may lead to issues because they may be used by the Windows Shell or other applications. Conversely, names such as OpenWithMyFineTool are more distinct and less likely to conflict.

Special Combinations

Setting Verb to an empty string and Caption to - will create a context menu separator.

Setting Caption to -> and Verb to Send To will create a "Send To" submenu that will be automatically populated by the Windows Shell.

add_property Method

This method is used to provide a value of a property of an item during folder enumeration.

Syntax

def add_property(task_id: int, format_id: str, property_id: int, prop_type: int, numeric_value: int, date_value: datetime.datetime, string_value: str) -> None: ...

Remarks

This method provides the system with information about a property for an item referenced in the on_get_properties event. This method should only be called from within the on_get_properties event handler. When a folder is displayed as a table ("Details" view mode), and a column exists for the specified property type, the provided value of the item property is displayed in the corresponding column according to the column definition. Please refer to the Property System section for additional details.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the on_get_properties event.

The FormatId parameter specifies the GUID of the property format. This acts as a broad identifier for a set of related properties and their corresponding columns. Its value must be specified in Registry Format. For instance: {1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}.

The PropertyId parameter specifies the ID of the property. Its value is used to identify each property distinctly in a group that shares the same GUID.

The PropType parameter specifies the data type of the value associated with the property. It should be set to one of the following:

The NumericValue parameter specifies the value of the property depending on the value of PropType. If PropType is equal to PROP_TYPE_LONG, the value of the property will be set to the provided integer value. When PropType is set to PROP_TYPE_BOOL, the property's value will be true if NumericValue is a non-zero value, and false otherwise. In the case where PropType is set to PROP_TYPE_ICON, NumericValue indicates the index of an icon to display from a property description schema. In all other cases, its value is ignored.

The DateValue parameter specifies the date value of the property only when PropType is set to PROP_TYPE_DATE.

The StringValue parameter specifies the text value of the property only when PropType is set to PROP_TYPE_STRING.

Icon Columns

In order for an icon column to be displayed in a folder, a property must be added that specifies the icon that will be displayed for each item. To add this property, the following steps need to be taken:

• Set the FormatId parameter to the value of the "formatID" attribute of the "propertyDescription" tag of the property that describes the visual representation of the column. In the sample schema from the Property System topic, this property is "MyCoolApp.MyIconUI", and FormatId would be set to {d9f69df5-01ef-4838-acb7-055012a678ca}.
• Set the PropertyId parameter to the value of the "propID" attribute of the "propertyDescription" tag of the property that describes the visual representation of the column. In the sample schema from the Property System topic, this property is "MyCoolApp.MyIconUI", and PropertyId would be set to 3.
• Set PropertyType to PROP_TYPE_ICON and set NumericValue to the index of the desired icon in the list of valid icons. This list is defined in a property schema, within the definition for a property that describes the set of icons that can be displayed. In the sample schema from the Property System topic, this property corresponds to "MyCoolApp.MyIconSource". In that case, NumericValue would be set to one of the values specified in the "value" attribute of the "enum" tags that correspond to that property.

Static Infotips

To set a static infotip for an item, the following two properties must be added. Alternatively, the infotip text can be provided dynamically by handling the on_get_info_tip event.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

deactivate Method

This method tells the class to stop handling the requests sent to the namespace extension.

Syntax

def deactivate() -> None: ...

Remarks

Use this method to stop handling requests that come from the Windows Shell via the native proxy DLL.

hide_info_bar Method

This method hides a previously shown information bar.

Syntax

def hide_info_bar(folder_id: str, info_bar_id: str) -> None: ...

Remarks

This method is used to hide an information bar previously shown using the show_info_bar method or the on_get_info_bar event.

The FolderId parameter should be set to an Id of a folder for which the bar was shown.

The InfoBarId parameter should be set to the GUID that was associated with the information bar when it was shown.

initialize Method

This method initializes the core library.

Syntax

def initialize() -> None: ...

Remarks

This method initializes the core library and must be called each time the application starts before attempting to use other class's methods. The two exceptions are install and uninstall, which don't require advance initialization.

If the application explicitly specifies the path to the proxy DLL, it should do this through the proxy_path property before calling this method.

install Method

This method registers Windows Shell folder information to the system.

Syntax

def install() -> None: ...

Remarks

This method is used to install the proxy DLL that integrates with the Windows Shell and register folder information with the system.

Before calling this method, you may change the default values of the attributes, display_name, icon_location, location, proxy_path, and scope properties. All of these values are used during installation and are placed in the Windows registry. Configuration settings, if used, also should be set using the config method before the call to install.

Registry Scope and User Permissions

The scope property specifies whether the information is written to the registry for the current user or for all users.

In the latter case, administrative rights are required to execute this method successfully. If the user account of the process that calls this method does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

list_item Method

This method is used to provide information about an item during folder enumeration.

Syntax

def list_item(task_id: int, id: str, attributes: int, size: int, display_name: str, file_system_path: str, icon_path: str, icon_index: int) -> None: ...

Remarks

This method is used to provide the system with information about an item contained in the folder being listed. This method should only be called from within the on_list_items event.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the on_list_items event.

The Id parameter should be set to the Id of the item or subfolder. This Id must be unique within the virtual filesystem represented by the class.

The Attributes parameter specifies the attributes of the item. Use the SFGAO_FOLDER attribute to indicate that an item is a folder. Available attributes are:

The default values for Attributes of virtual items are listed below. This is only applicable when FileSystemPath is empty.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM

The default attributes for virtual folders are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_BROWSABLE
• SFGAO_FOLDER
• SFGAO_HASSUBFOLDER

The default values for Attributes of physical items are listed below. This is only applicable when FileSystemPath specifies the path to the file or folder on disk.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_FILESYSTEM

The default attributes for physical folders are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_BROWSABLE
• SFGAO_FOLDER
• SFGAO_FILESYSTEM
• SFGAO_HASSUBFOLDER

The Size parameter can be used to specify the size of the item data that one may copy. Set the value to -1 to tell the class that an item has no data available for reading. When this value is set, on_get_item_data does not fire. The parameter is ignored for items with FileSystemPath set as well as for folders.

The DisplayName parameter specifies the human-readable name of the item. This may be the name of a file or directory represented by this item, or some other meaningful text for a user.

The FileSystemPath specifies the path to the file on disk if the item is a physical file and represents a file or directory on a filesystem. If the item is virtual and has no representation on a filesystem, pass an empty string for this parameter. See the Physical and Virtual Windows Shell Items topic in the introduction for additional information.

The IconPath parameter specifies the path to the DLL or EXE file that contains the icon for the item.

The IconIndex parameter determines which icon is displayed for the item. Its value may be either the index or Id of the specific icon within the resources of the DLL or EXE file in IconPath. Note that an index must be a positive number, while an Id value must be a negative number.

refresh_folder Method

This method notifies the class and the Windows Shell that a folder or an item has changed.

Syntax

def refresh_folder(item_id: str, action: int, new_id: str, refresh_view: int) -> bool: ...

Remarks

If a folder is modified by some means external to the Windows Shell, this method should be called to notify the Windows Shell and the class about the change. Doing so prompts the Windows Shell to make any requests necessary to obtain the most up-to-date information, which in turn may fire the relevant class events.

If an item or folder is added, this refresh_folder method should be called for a parent folder (see details below).

ItemId specifies the Id of the folder that has changed. This is the Id that an application has previously provided when using the list_item method to add a folder. When a new item or folder was or is about to be listed with the list_item method, ItemId should be set to the Id of the new item's parent folder.

Action specifies the type(s) of change so that the OS knows what kind of information it needs to request. The value is a combination of the following flags:

The NewId parameter is the Id of an item that has been newly created or renamed. When listing a new item using the list_item method, NewId should be set to its new Id. Similarly if a folder is renamed and listed again, its Id will change. In this case, the NewId should be set to the new Id of the renamed folder. In all other cases, the value of NewId is ignored.

The RefreshView parameter tells the class to request a refresh of related Windows Shell views. If a refresh is requested for the item that is not a folder, a parent folder is refreshed instead. The value can be one of the following:

Listing Multiple Items

When listing several children items in a batch with the list_item method, it is recommended to first set RefreshView to REFRESH_VIEW_NO_REFRESH before the items are listed. Then, the refresh_view method should be called separately after all of the items have been reported.

refresh_item Method

This method notifies the class and the Windows Shell that an item has changed.

Syntax

def refresh_item(item_id: str, action: int, new_item_id: str, refresh_view: int) -> bool: ...

Remarks

If an item is modified by some means external to the Windows Shell, this method should be called to notify the Windows Shell and the class about the change. Doing so prompts the Windows Shell to make any requests necessary to obtain the most up-to-date information, which in turn may fire the relevant class events.

ItemId specifies the Id of the item that has changed. This is the Id that an application has previously provided when using the list_item method to add an item.

Action specifies the type(s) of change so that the OS knows what kind of information it needs to request. The value is a combination of the following flags:

The NewId parameter is the Id of a newly renamed item. When an item is renamed, its Id will change and its new Id should be passed into NewId.

The RefreshView parameter tells the class to request a refresh of related Windows Shell views. If a refresh is requested for the item that is not a folder, a parent folder is refreshed instead. The value can be one of the following:

Listing Multiple Items

When listing several children items in a batch with the list_item method, it is recommended to first set RefreshView to REFRESH_VIEW_NO_REFRESH before the items are listed. Then, the refresh_view method should be called separately after all of the items have been reported.

refresh_view Method

This method notifies the Windows Shell that item views must be refreshed.

Syntax

def refresh_view(item_id: str, refresh_view: int) -> None: ...

Remarks

If an item or folder is modified, an application may request a visual refresh of the folder views that are opened for the item identified by ItemId. If a refresh is requested for the item that is not a folder, a parent folder is refreshed instead.

The RefreshView parameter tells the class to request a refresh of related Windows Shell views. The value can be one of the following:

register_schema Method

This method is used to register a property schema with the Windows Shell.

Syntax

def register_schema(file_name: str) -> None: ...

Remarks

This method registers a property schema with the Windows Shell. This should normally be done once per application installation. Please refer to the Property System topic in the introduction section for additional details. To unregister the property schema, use unregister_schema.

The FileName parameter specifies the XML file with the property schema.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

remove_menu_item Method

This method is used to remove an existing menu item from a context menu.

Syntax

def remove_menu_item(task_id: int, verb: str) -> None: ...

Remarks

This method may be called from within on_merge_menu, on_merge_menu_top, and on_merge_menu_bottom event handlers to remove a menu item from a context menu.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the corresponding event.

The Verb parameter is an identifier of the menu item to be removed and must be present in the ExistingVerbs list received by the event handler.

If an item has children (i.e., constitutes a submenu), the whole submenu gets removed.

show_info_bar Method

This method shows an information bar for a folder.

Syntax

def show_info_bar(folder_id: str, info_bar_id: str, text: str) -> None: ...

Remarks

This method displays an information bar for a folder at the top of Windows File Explorer view.

The FolderId parameter specifies the item Id of the folder for which the information bar will be displayed. If the folder specified by FolderId is not visible, the information bar will not be shown.

The InfoBarId parameter specifies the GUID of the information bar. This acts as an identifier that can be used to hide the bar later. If set to an empty value, the information bar will not be displayed. The GUID must be specified in Registry Format. For instance: {1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}.

The Text parameter is the text content to be displayed in the information bar. If set to an empty value, the information bar will not be displayed.

uninstall Method

This method unregisters Windows Shell folder information from the system.

Syntax

def uninstall() -> None: ...

Remarks

This method is used to uninstall the native DLL that integrates with the Windows Shell from the system.

Before calling this method, you may change the default value of the scope property.

Registry Scope and User Permissions

The scope property specifies whether the information is written to the registry for the current user or for all users.

In the latter case, administrative rights are required to execute this method successfully. If the user account of the process that calls this method does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Handling Multiple Components

As ShellFolder and ShellMenu classes share a proxy DLL and a product GUID, they store some common information in a registry key. Calling the Uninstall method of one of the components will delete a shared registry key as well.

Each class should be uninstalled properly by calling the corresponding Uninstall method. At the same time, if an application needs to uninstall just one class and keep the other(s), it should call the Uninstall method of that class and then call the Install method of the other classes to restore the common information in the shared registry key.

unregister_schema Method

This method is used to unregister a property schema from the Windows Shell.

Syntax

def unregister_schema(file_name: str) -> None: ...

Remarks

This method unregisters a previously registered property schema from the Windows Shell. This should normally be done once per application deinstallation. Please refer to the Property System section for additional details.

The FileName parameter specifies the XML file with the property schema.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

on_compare_items Event

This event is fired when the folder sorts items and needs to compare two items during sorting.

Syntax

class ShellFolderCompareItemsEventParams(object):
  @property
  def item1_id() -> str: ...

  @property
  def item2_id() -> str: ...

  @property
  def column_format_id() -> str: ...

  @property
  def column_property_id() -> int: ...

  @property
  def options() -> int: ...

  @property
  def handled() -> bool: ...
  @handled.setter
  def handled(value) -> None: ...

  @property
  def result() -> int: ...
  @result.setter
  def result(value) -> None: ...

# In class ShellFolder:
@property
def on_compare_items() -> Callable[[ShellFolderCompareItemsEventParams], None]: ...
@on_compare_items.setter
def on_compare_items(event_hook: Callable[[ShellFolderCompareItemsEventParams], None]) -> None: ...

Remarks

This event fires when two items need to be compared during sorting. The event is useful for implementing custom sorting functionality that extends beyond the system's built-in comparison mechanism.

Note: This event will only fire when the FireCompareItems configuration setting is set to True.

The Item1Id and Item2Id parameters are Ids of the of the items that are being compared.

The ColumnFormatId and ColumnPropertyId parameters respectively specify the format ID and property ID of the column that is being sorted by. These values can be used to identify this column when the event is fired.

The Options parameter contains additional sorting options. Its value may be one of the following flags:

The Result parameter indicates the outcome of the comparison. This value must be set to -1 to indicate that the first item precedes the second, to 0 to indicate that the items are equal, or to 1 to indicate that the second item precedes the first one.

The Handled parameter determines if the class should use the value specified in Result to compare the two items the event was fired for. This value should be set to True to tell the class to use the value specified in Result to compare the items. Set this to False to ignore the value specified in Result and use the system's built-in comparison mechanism instead. By default, this parameter is set to False.

on_delete_item Event

This event is fired when an item is deleted.

Syntax

class ShellFolderDeleteItemEventParams(object):
  @property
  def item_id() -> str: ...

  @property
  def recycle() -> bool: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_delete_item() -> Callable[[ShellFolderDeleteItemEventParams], None]: ...
@on_delete_item.setter
def on_delete_item(event_hook: Callable[[ShellFolderDeleteItemEventParams], None]) -> None: ...

Remarks

This event fires when an item is deleted.

The ItemId parameter is the item Id of the of the deleted item.

The Recycle parameter indicates that the item is being sent to the Recycle Bin. When set to true, it indicates that the item can be restored later.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_drag Event

This event is fired when a drag operation starts or when an item is dragged over another item in the folder.

Syntax

class ShellFolderDragEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def target_id() -> str: ...

  @property
  def drag_type() -> int: ...

  @property
  def key_state() -> int: ...

  @property
  def effects() -> int: ...
  @effects.setter
  def effects(value) -> None: ...

  @property
  def formats() -> str: ...
  @formats.setter
  def formats(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_drag() -> Callable[[ShellFolderDragEventParams], None]: ...
@on_drag.setter
def on_drag(event_hook: Callable[[ShellFolderDragEventParams], None]) -> None: ...

Remarks

This event is fired when a drag operation starts or when an item is dragged over another item in the virtual folder.

The TaskId parameter identifies the current operation. The drag_data collection will contain the same set of items associated with the ongoing drag operation for each for each unique TaskId.

The TargetId parameter is the item Id of the drop target. This is the identifier of the item in the virtual folder that is underneath the dragged item. An empty TargetId indicates that the drop target is the root folder of the Windows Shell Namespace branch.

The DragType parameter indicates the type of drag operation being performed. Its value can be the one of the following:

The KeyState parameter contains the current state of the modifier keys on the keyboard. Its value is not available when DragType is equal to DRAG_TYPE_START. Possible values can be a combination of any of these flags:

The Effects parameter specifies the operations that are available to the user performing the drag operation. The parameter can be modified to change these operations only when DragType is not equal to DRAG_TYPE_LEAVE. Its value is a combination of the following flags, OR'd together:

The value may also include the highest bit set (the mask would be 0x80000000) which indicates that scrolling is occuring at the moment.

The Formats parameter contains the data formats in which the drag data is available to the target of the operation. The parameter can be used to determine how the target can handle the drag data. Its value is a list of text strings that represent different data formats, with each format separated by the LF character (numeric code 10). Possible formats may include the known formats listed below, or some other format values defined by the source of the operation.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Drag Data

When the event is fired and the DragType is either DRAG_TYPE_ENTER or DRAG_TYPE_OVER, an application will be able to access the data associated with the drag operation through the drag_data collection. In these cases, the list of formats in which this data is available will be accessible via the Formats parameter.

If the event is fired and the DragType is DRAG_TYPE_START, the application will be responsible for defining the formats in which it can provide this data. To do this, it should populate the Formats parameter with the clipboard format Ids or registered names (an Id is recommended) of each intended format as a string, where each format is separated with the LF character (numeric code 10). Following this, the on_get_drag_data event will fire right after this one to collect the data of the ongoing drag operation for each of the formats specified in the Formats parameter.

Drag Data Formats

In Windows, data formats used in clipboard or drag-and-drop operations are identified with unique numeric codes known as clipboard format Ids. Along with these Ids, formats may also be identified with a text identifier known as a clipboard format name. These identifiers can represent either predefined data formats recognized by the system, or custom data formats defined by third-party applications. More information about these formats can be found in the MSDN topic for Clipboard Formats.

When the event fires and the class populates the contents of the Formats parameter, the formats listed may be represented with either types of identifiers. Additionally, the Format and FormatName properties of the elements in drag_data collection will be automatically populated by the class depending on the available identifiers for each of the listed formats. If a given format has a clipboard format name, the Formats parameter will contain its format name, and the FormatName field of the corresponding DragItem element will be set. If the format also has a clipboard format Id, the Format field of the corresponding DragItem element will be set to a non-zero value. Finally, if the format only has a clipboard format Id, its value will be used to represent the format in the Formats parameter. In this case, the Format field of the corresponding DragItem element will be set, while its FormatName field will be empty.

on_drop Event

This event is fired when a drag operation finishes with a drop over an item or folder or when the clipboard data is pasted into a folder.

Syntax

class ShellFolderDropEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def target_id() -> str: ...

  @property
  def key_state() -> int: ...

  @property
  def effects() -> int: ...
  @effects.setter
  def effects(value) -> None: ...

  @property
  def formats() -> str: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_drop() -> Callable[[ShellFolderDropEventParams], None]: ...
@on_drop.setter
def on_drop(event_hook: Callable[[ShellFolderDropEventParams], None]) -> None: ...

Remarks

This event is fired when a drag operation finishes with a drop over an item inside the virtual folder. The event also fires when clipboard data is pasted into the virtual folder.

The TaskId parameter identifies the current operation. During the drag operation identified by the same TaskId, the drag_data collection contains the same data items, associated with this drag operation.

The TargetId parameter is the item Id of the drop target. This is the identifier of the item in the virtual folder underneath the dragged item when it was dropped. An empty TargetId indicates that the drop target is the root folder of the Windows Shell Namespace branch.

The KeyState parameter contains the current state of the modifier keys on the keyboard. Possible values can be a combination of any of these flags:

The Effects parameter specifies the operations that are available to the user performing the drag operation. The parameter can be modified to change the allowed operations for the current drag operation. Its value is a combination of the following flags, OR'd together:

The value may also include the highest bit set (the mask would be 0x80000000) which indicates that scrolling is occuring at the moment.

The Formats parameter contains the data formats in which the drag data is available to the target of the operation. The parameter can be used to determine how the target can handle the drag data. Its value is a list of text strings that represent different data formats, with each format separated by the LF character (numeric code 10). Possible formats may include the known formats listed below, or some other format values defined by the source of the operation.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Drag Data Formats

In Windows, data formats used in clipboard or drag-and-drop operations are identified with unique numeric codes known as clipboard format Ids. Along with these Ids, formats may also be identified with a text identifier known as a clipboard format name. These identifiers can represent either predefined data formats recognized by the system, or custom data formats defined by third-party applications. More information about these formats can be found in the MSDN topic for Clipboard Formats.

When the event fires and the class populates the contents of the Formats parameter, the formats listed may be represented with either types of identifiers. Additionally, the Format and FormatName properties of the elements in drag_data collection will be automatically populated by the class depending on the available identifiers for each of the listed formats. If a given format has a clipboard format name, the Formats parameter will contain its format name, and the FormatName field of the corresponding DragItem element will be set. If the format also has a clipboard format Id, the Format field of the corresponding DragItem element will be set to a non-zero value. Finally, if the format only has a clipboard format Id, its value will be used to represent the format in the Formats parameter. In this case, the Format field of the corresponding DragItem element will be set, while its FormatName field will be empty.

on_error Event

This event is fired if an unhandled error occurs during an event.

Syntax

class ShellFolderErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class ShellFolder:
@property
def on_error() -> Callable[[ShellFolderErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[ShellFolderErrorEventParams], None]) -> None: ...

Remarks

This event fires if an unhandled error occurs. Developers can use this information to track down unhandled errors that occur in the class.

ErrorCode contains an error code and Description contains a textual description of the error.

on_get_columns Event

This event is fired when columns of a folder need to be added.

Syntax

class ShellFolderGetColumnsEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def folder_id() -> str: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_get_columns() -> Callable[[ShellFolderGetColumnsEventParams], None]: ...
@on_get_columns.setter
def on_get_columns(event_hook: Callable[[ShellFolderGetColumnsEventParams], None]) -> None: ...

Remarks

This event is fired when the system requests information about a folder's columns. An event handler for this event determines the columns that are included in the folder. These are added by calling either one of the add_column or add_icon_column methods from within the handler.

Note: The class automatically adds a display name column and a column for item icons by default.

The event is fired when items are enumerated using the on_list_items event, for each listed folder, right after all items have been reported and after on_get_properties was fired for the folder identified by FolderId. For the root folder, the event is fired when the class is activated using the activate method.

The TaskId parameter identifies the current operation. Its value is required when calling the add_column method.

The FolderId parameter contains the item Id of the folder for which column information is being requested. An empty value for FolderId denotes the root folder of the Windows Shell Namespace branch.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_get_drag_data Event

This event is fired when a drag operation has started and the class needs to collect data for the drag operation.

Syntax

class ShellFolderGetDragDataEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def format() -> int: ...

  @property
  def buffer() -> c_void_p: ...

  @property
  def bytes_to_read() -> int: ...
  @bytes_to_read.setter
  def bytes_to_read(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_get_drag_data() -> Callable[[ShellFolderGetDragDataEventParams], None]: ...
@on_get_drag_data.setter
def on_get_drag_data(event_hook: Callable[[ShellFolderGetDragDataEventParams], None]) -> None: ...

Remarks

This event is fired when a drag operation has started within the virtual folder and the class needs to collect data for the drag operation. The event fires twice for each format supported for the ongoing operation. Initially, it fires to obtain the size of the drag data it needs to collect (see below for details). After the class obtains the size information, the event fires once more to collect the data for a given format associated with the ongoing drag-and-drop operation.

The TaskId parameter is set to the same value as in the on_drag event fired when the drag-and-drop operation started.

The Format contains the clipboard format Id of the format in which the data is required. This will be one of the formats reported as supported by the on_drag event.

The Buffer parameter acts as the destination buffer for the data being requested. If the event fires and the number of bytes specified by the BytesToRead parameter is sufficient to store the drag data, the event handler should copy the data into the Buffer. In this case, the BytesToRead parameter must be set to the actual number of bytes copied into the Buffer, and the ResultCode parameter must be set to 0.

The BytesToRead parameter indicates the size of the data that is being requested. When the event first fires to request the size of the drag data, its value will be set to 0. If the event fires and the number of bytes specified in BytesToRead is less than the size of the drag data that will be copied into the destination Buffer, this parameter should be set to the size of the drag data and the ResultCode parameter must be set to CBFSSHELL_ERR_INSUFFICIENT_BUFFER.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_get_info_bar Event

This event is fired to show an information bar for a folder that is about to be displayed.

Syntax

class ShellFolderGetInfoBarEventParams(object):
  @property
  def folder_id() -> str: ...

  @property
  def info_bar_id() -> str: ...
  @info_bar_id.setter
  def info_bar_id(value) -> None: ...

  @property
  def text() -> str: ...
  @text.setter
  def text(value) -> None: ...

# In class ShellFolder:
@property
def on_get_info_bar() -> Callable[[ShellFolderGetInfoBarEventParams], None]: ...
@on_get_info_bar.setter
def on_get_info_bar(event_hook: Callable[[ShellFolderGetInfoBarEventParams], None]) -> None: ...

Remarks

This event is fired by the class when the Windows Shell is going to display a folder. It provides an opportunity to immediately display an information bar for the folder. Alternatively, an information bar can be displayed at another time by using the show_info_bar method.

The FolderId parameter specifies the item Id of the folder for which the information bar will be displayed. If the folder specified by FolderId is not visible, the information bar will not be shown.

The InfoBarId parameter specifies the GUID of the information bar. This acts as an identifier that can be used to hide the bar later. If set to an empty value, the information bar will not be displayed. The GUID must be specified in Registry Format. For instance: {1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}.

The Text parameter is the text content to be displayed in the information bar. If set to an empty value, the information bar will not be displayed.

on_get_info_tip Event

This event is fired when the infotip of an item is about to be displayed.

Syntax

class ShellFolderGetInfoTipEventParams(object):
  @property
  def item_id() -> str: ...

  @property
  def info_tip() -> str: ...
  @info_tip.setter
  def info_tip(value) -> None: ...

# In class ShellFolder:
@property
def on_get_info_tip() -> Callable[[ShellFolderGetInfoTipEventParams], None]: ...
@on_get_info_tip.setter
def on_get_info_tip(event_hook: Callable[[ShellFolderGetInfoTipEventParams], None]) -> None: ...

Remarks

This event is fired by the class when the Windows Shell is going to display an infotip for an item. The event provides an opportunity to dynamically add an infotip by modifying the event's parameters. Alternatively, an infotip can be set statically via the add_property method.

The ItemId parameter contains the item Id of the item for which the infotip will be displayed.

The InfoTip parameter specifies the text content of the infotip.

on_get_item_data Event

This event is fired when the Windows Shell is reading the contents of an item.

Syntax

class ShellFolderGetItemDataEventParams(object):
  @property
  def item_id() -> str: ...

  @property
  def start() -> int: ...

  @property
  def length() -> int: ...
  @length.setter
  def length(value) -> None: ...

  @property
  def buffer() -> c_void_p: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_get_item_data() -> Callable[[ShellFolderGetItemDataEventParams], None]: ...
@on_get_item_data.setter
def on_get_item_data(event_hook: Callable[[ShellFolderGetItemDataEventParams], None]) -> None: ...

Remarks

This event is fired by the class when the Windows Shell needs to read a block of data from an item. An event handler for this event is responsible for populating the contents of the items in the virtual folder by providing this data as it is requested.

The event does not fire for physical items (i.e., the ones backed by a file on the existing filesysten) and for items, whose size was previously set to -1.

The ItemId parameter contains the Id of the item for which data is requested.

The Start parameter contains the number of bytes of data for the current item that have already been read by the system. It specifies the starting position for copying data into the Buffer parameter.

The Length parameter specifies the maximum number of bytes the system will read from the data provided. Its value should be set to the actual number of bytes that will be written to the Buffer parameter.

The Buffer parameter acts as the destination buffer for the data being requested. An event handler should copy up to Length bytes from the item's data source into Buffer, starting at the position specified by the Start parameter. To copy the data from a bytes or bytearray variable, use the code similar to the following: all_item_data = ... # all of your item's data here event_args.length = min(event_args.length, len(all_item_data) - event_args.start) item_data_to_copy = all_item_data[event_args.start:event_args.start + event_args.length] ptr = cast(c_char_p(bytes(memoryview(item_data_to_copy))), c_void_p) memmove(event_args.buffer, ptr, event_args.length)

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

The event handler may set ResultCode to CBFSSHELL_ERR_STREAM_EOF if no data could be read at all. If at least one byte was read and has to be passed to the Windows Shell, set ResultCode to 0 instead.

on_get_item_id Event

This event is fired when the system needs the identifier of an item.

Syntax

class ShellFolderGetItemIdEventParams(object):
  @property
  def parent_id() -> str: ...

  @property
  def display_name() -> str: ...

  @property
  def item_id() -> str: ...
  @item_id.setter
  def item_id(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_get_item_id() -> Callable[[ShellFolderGetItemIdEventParams], None]: ...
@on_get_item_id.setter
def on_get_item_id(event_hook: Callable[[ShellFolderGetItemIdEventParams], None]) -> None: ...

Remarks

This event is fired by the class when it needs to find the identifier of an item defined by its display name.

The ParentId parameter contains the Id of the parent of the item that needs to be identified.

The DisplayName parameter contains the display name of the item that needs to be identified.

The ItemId parameter specifies the Id of the item that needs to be identified. This value should be set to the Id of the item with a display name equal to DisplayName. If the item cannot be found, ItemId should be set to an empty value. If an item Id is specified by the event handler, the class will fire the on_get_item_info event to retrieve more information about the item.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

If an item with the given display name has not been found (which may be the case when a new item is attempted to be created), the handler should set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

on_get_item_info Event

This event is fired when information about an item needs to be retrieved.

Syntax

class ShellFolderGetItemInfoEventParams(object):
  @property
  def item_id() -> str: ...

  @property
  def attributes() -> int: ...
  @attributes.setter
  def attributes(value) -> None: ...

  @property
  def size() -> int: ...
  @size.setter
  def size(value) -> None: ...

  @property
  def display_name() -> str: ...
  @display_name.setter
  def display_name(value) -> None: ...

  @property
  def file_system_path() -> str: ...
  @file_system_path.setter
  def file_system_path(value) -> None: ...

  @property
  def icon_path() -> str: ...
  @icon_path.setter
  def icon_path(value) -> None: ...

  @property
  def icon_index() -> int: ...
  @icon_index.setter
  def icon_index(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_get_item_info() -> Callable[[ShellFolderGetItemInfoEventParams], None]: ...
@on_get_item_info.setter
def on_get_item_info(event_hook: Callable[[ShellFolderGetItemInfoEventParams], None]) -> None: ...

Remarks

This event is fired when the class needs to retrieve information about an item. The event will also fire when the refresh_item method is called and the class needs to update cached information about an item.

The ItemId parameter contains the Id of the item for which information will be retrieved.

The Attributes parameter is used to specify the attributes of the item. When there exists some cached information that needs to be updated, the value of this parameter is non-zero. If this is the case, changing of the SFGAO_FOLDER flag has no effect (this flag will be set by class to the existing value). Available attributes are:

The default values for Attributes of virtual items are listed below. This is only applicable when FileSystemPath is empty.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM

The default attributes for virtual folders are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_BROWSABLE
• SFGAO_FOLDER
• SFGAO_HASSUBFOLDER

The default values for Attributes of physical items are listed below. This is only applicable when FileSystemPath specifies the path to the file or folder on disk.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_FILESYSTEM

The default attributes for physical folders are as follows.

• SFGAO_CANLINK
• SFGAO_STORAGE
• SFGAO_HASPROPSHEET
• SFGAO_STREAM
• SFGAO_STORAGEANCESTOR
• SFGAO_BROWSABLE
• SFGAO_FOLDER
• SFGAO_FILESYSTEM
• SFGAO_HASSUBFOLDER

The Size parameter can be used to specify the size of the item data that one may copy. Set the value to -1 to tell the class that an item has no data available for reading. When this value is set, on_get_item_data does not fire. The parameter is ignored for items with FileSystemPath set as well as for folders.

The DisplayName parameter specifies the human-readable name of the item. This may be the name of a file or directory represented by this item, or some other meaningful text for a user.

The FileSystemPath specifies the path to the file on disk if the item is a physical file and represents a file or directory on a filesystem. If the item is virtual and has no representation on a filesystem, pass an empty string for this parameter. See the Physical and Virtual Windows Shell Items topic in the introduction for additional information.

The IconPath parameter specifies the path to the DLL or EXE file that contains the icon for the item.

The IconIndex parameter determines which icon is displayed for the item. Its value may be either the index or Id of the specific icon within the resources of the DLL or EXE file in IconPath. Note that an index must be a positive number, while an Id value must be a negative number.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_get_name_limits Event

This event is fired to collect information about naming constraints for items in a folder.

Syntax

class ShellFolderGetNameLimitsEventParams(object):
  @property
  def folder_id() -> str: ...

  @property
  def max_length() -> int: ...
  @max_length.setter
  def max_length(value) -> None: ...

  @property
  def allowed_chars() -> str: ...
  @allowed_chars.setter
  def allowed_chars(value) -> None: ...

  @property
  def disallowed_chars() -> str: ...
  @disallowed_chars.setter
  def disallowed_chars(value) -> None: ...

# In class ShellFolder:
@property
def on_get_name_limits() -> Callable[[ShellFolderGetNameLimitsEventParams], None]: ...
@on_get_name_limits.setter
def on_get_name_limits(event_hook: Callable[[ShellFolderGetNameLimitsEventParams], None]) -> None: ...

Remarks

This event fires to retrieve optional information about constraints that should be applied when an item is created or renamed. If the event is not handled or the corresponding parameter is not set, default values apply.

The FolderId parameter contains the item Id of the folder, items of which will be created or rename. An empty value for FolderId indicates the root folder of the Windows Shell Namespace branch.

The MaxLength parameter specifies the maximum character length of the item's display name. Its value is set to 0 by default.

The AllowedChars parameter defines the set of characters allowed in the item's display name. Its value is case-sensitive. An empty value indicates that any character is allowed except for the ones specified in the DisallowedChars parameter.

The DisallowedChars parameter defines the set of characters that are not allowed in the item's display name. Its value case-sensitive and is only considered when AllowedChars is set to an empty value. When the event fires, its value is set to "/:*?"<>|" by default.

on_get_properties Event

This event is fired when the properties of an item need to be listed.

Syntax

class ShellFolderGetPropertiesEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def item_id() -> str: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_get_properties() -> Callable[[ShellFolderGetPropertiesEventParams], None]: ...
@on_get_properties.setter
def on_get_properties(event_hook: Callable[[ShellFolderGetPropertiesEventParams], None]) -> None: ...

Remarks

This event is fired by the class when it needs to retrieve properties of an item. The event is fired for each item listed during the on_list_items event, right after all items have been reported. An event handler for this event determines the properties of each item as they are enumerated. To assign these properties, the add_property method should be called within the handler for each property that will be added to the item.

The ItemId parameter contains the item Id of the item for which properties are being retrieved.

The TaskId parameter identifies the current operation and is required when calling the add_property method.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Virtual Item Data

When adding the properties of a virtual item that contains data, it is important to pass its data size to the class. This ensures that the component can properly fire the on_get_item_data event when the item is copied or accessed. This is done by adding a property using add_property with the following parameters:

• Set the FormatId parameter to b725f130-47ef-101a-a5f1-02608c9eebac.
• Set the PropertyId parameter to 12.
• Set the PropType parameter to PROP_TYPE_LONG.

An sample call to add this propety would be: MyShellFolder.AddProperty(TaskId, "b725f130-47ef-101a-a5f1-02608c9eebac", 12, 2, ItemDataLength, DateTime.MinValue, null);

on_invoke_menu Event

This event is fired when an item of the context menu is invoked.

Syntax

class ShellFolderInvokeMenuEventParams(object):
  @property
  def verb() -> str: ...

  @property
  def folder_id() -> str: ...

# In class ShellFolder:
@property
def on_invoke_menu() -> Callable[[ShellFolderInvokeMenuEventParams], None]: ...
@on_invoke_menu.setter
def on_invoke_menu(event_hook: Callable[[ShellFolderInvokeMenuEventParams], None]) -> None: ...

Remarks

This event is fired when a context menu item is invoked. To obtain the list of Windows Shell items for which the context menu was invoked, use the selected_items property.

The Verb parameter contains the unique text identifier of the menu item that was invoked.

The FolderId parameter contains the item Id of the folder where the context menu was invoked.

Menu Items from a "New" Submenu

The Windows Shell appends a "New" submenu to the context menu when a menu item is added with the on_merge_menu_top event with its ShowNewMenu parameter set to True. This submenu comes with a set of predefined operations, each with their own respective verbs. An event handler for this method may use these verbs to handle the operations that correspond to the items within this submenu. The possible values for these verbs include:

• The newfolder verb for creating a new folder.
• The newlink verb for creating a new shortcut.
• A file extension verb, such as .txt, for creating a new file of its respective type.

UI Considerations

Event handlers are called in the context of threads that run in the MTA (multithreaded apartment) state. This state is not suitable for showing UI elements. Thus, event handlers should create an STA thread and use it to display a needed window. For example:

var thread = new Thread(() => { ... } // "..." is the code that an event handler executes in a helper thread thread.SetApartmentState(ApartmentState.STA); thread.IsBackground = true; thread.Start(); thread.Join(); // optional, if your code should work synchronously

on_list_items Event

This event is fired when the contents of a folder are listed.

Syntax

class ShellFolderListItemsEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def parent_id() -> str: ...

  @property
  def flags() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_list_items() -> Callable[[ShellFolderListItemsEventParams], None]: ...
@on_list_items.setter
def on_list_items(event_hook: Callable[[ShellFolderListItemsEventParams], None]) -> None: ...

Remarks

This event is fired when the system requests information about a folder's contents. An event handler for this event determines the items and subfolders that get included in the folder. To include them, the list_item method should be called within the handler for each individual item and subfolder that will be in the folder.

The on_get_properties event will fire for each of the listed items. Following this, the on_get_columns event and then the on_get_name_limits event will sequentially fire for each of the listed folders.

The TaskId parameter identifies the current operation and is required when calling the list_item method.

The ParentId parameter is the item Id of the folder being listed. An empty value indicates that the root folder is being listed.

The Flags parameter controls the types of items included in the folder. Its value may be one or more of the following flags OR'd together:

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_merge_menu Event

This event is fired when a context menu is shown for one or more items.

Syntax

class ShellFolderMergeMenuEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def folder_id() -> str: ...

  @property
  def existing_verbs() -> str: ...

  @property
  def flags() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_merge_menu() -> Callable[[ShellFolderMergeMenuEventParams], None]: ...
@on_merge_menu.setter
def on_merge_menu(event_hook: Callable[[ShellFolderMergeMenuEventParams], None]) -> None: ...

Remarks

This event is fired by the class when the Windows Shell is about to show a context menu for one or more Windows Shell items. To obtain the list of Windows Shell items for which the context menu is about to be displayed, use the selected_items property.

To handle the event properly, an event handler must call the add_menu_item method in a loop, with each additional menu command reported using a call to this method. The event handler should return when it finishes listing all menu items. An application may add own menu items and remove the existing ones on each step outlined above; however, each item needs to be added on just one step to prevent duplication.

The TaskId parameter identifies the current operation and is required when calling the add_menu_item method.

The FolderId parameter contains the item Id of the folder where the context menu was invoked.

The ExistingVerbs parameter contains a list of verbs for menu items already in the menu, separated with the LF character (numeric code 10). This list may include items from the Windows Shell, other Windows Shell extensions, or those added previously by the event handler. The event handler can use the remove_menu_item method to remove any of these existing menu items.

The Flags parameter contains various flags that determine the content and behavior of the menu. The list of valid values for this parameter can be found in the MSDN page for the IContextMenu::QueryContextMenu method under the list of CMF_* flags.

The ExistingVerbs parameter contains a list of verbs for menu items already in the menu, separated with the LF character (numeric code 10). This list may include items from the Windows Shell, other Windows Shell extensions, or those added previously by the event handler. The event handler can use the remove_menu_item method to remove any of these existing menu items.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

Menu Item Placement

The Windows Shell makes requests to merge a menu in three distinct phases. Initially, menu items are merged in an order defined by the system. In the second phase, additional items are placed at the bottom of the menu. The final phase adds items to the top of the menu. For each phase, the component triggers a corresponding event: on_merge_menu for the initial ordering, on_merge_menu_bottom for adding items to the bottom, and on_merge_menu_top for adding items to the top.

Some applications or Windows Shell extensions may need to add their menu items after the initial phase. Due to this, the last two events may be more appropriate for adding new items or removing those recently added by other applications..

on_merge_menu_bottom Event

This event is fired when a context menu is shown for one or more items.

Syntax

class ShellFolderMergeMenuBottomEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def folder_id() -> str: ...

  @property
  def existing_verbs() -> str: ...

  @property
  def flags() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_merge_menu_bottom() -> Callable[[ShellFolderMergeMenuBottomEventParams], None]: ...
@on_merge_menu_bottom.setter
def on_merge_menu_bottom(event_hook: Callable[[ShellFolderMergeMenuBottomEventParams], None]) -> None: ...

Remarks

This event is fired by the class when the Windows Shell is about to show a context menu for one or more Windows Shell items. Items added by an event handler are merged at the bottom of the existing menu. To obtain the list of Windows Shell items for which the context menu is about to be displayed, use the selected_items property.

To handle the event properly, an event handler must call the add_menu_item method in a loop, with each additional menu command reported using a call to this method. The event handler should return when it finishes listing all menu items. An application may add own menu items and remove the existing ones on each step outlined above; however, each item needs to be added on just one step to prevent duplication.

The TaskId parameter identifies the current operation and is required when calling the add_menu_item method.

The FolderId parameter contains the item Id of the folder where the context menu was invoked.

The ExistingVerbs parameter contains a list of verbs for menu items already in the menu, separated with the LF character (numeric code 10). This list may include items from the Windows Shell, other Windows Shell extensions, or those added previously by the event handler. The event handler can use the remove_menu_item method to remove any of these existing menu items.

The Flags parameter contains various flags that determine the content and behavior of the menu. The list of valid values for this parameter can be found in the MSDN page for the IContextMenu::QueryContextMenu method under the list of "CFM_* flags".

The ExistingVerbs parameter contains a list of verbs for menu items already in the menu, separated with the LF character (numeric code 10). This list may include items from the Windows Shell, other Windows Shell extensions, or those added previously by the event handler. The event handler can use the remove_menu_item method to remove any of these existing menu items.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_merge_menu_top Event

This event is fired when a context menu is shown for one or more items.

Syntax

class ShellFolderMergeMenuTopEventParams(object):
  @property
  def task_id() -> int: ...

  @property
  def folder_id() -> str: ...

  @property
  def existing_verbs() -> str: ...

  @property
  def flags() -> int: ...

  @property
  def show_new_menu() -> bool: ...
  @show_new_menu.setter
  def show_new_menu(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_merge_menu_top() -> Callable[[ShellFolderMergeMenuTopEventParams], None]: ...
@on_merge_menu_top.setter
def on_merge_menu_top(event_hook: Callable[[ShellFolderMergeMenuTopEventParams], None]) -> None: ...

Remarks

This event is fired by the class when the Windows Shell is about to show a context menu for one or more Windows Shell items. Items added by an event handler for this method are merged at the top of the existing menu. To obtain the list of Windows Shell items for which the context menu is about to be displayed, use the selected_items property.

To handle the event properly, an event handler must call the add_menu_item method in a loop, with each additional menu command reported using a call to this method. The event handler should return when it finishes listing all menu items. An application may add own menu items and remove the existing ones on each step outlined above; however, each item needs to be added on just one step to prevent duplication.

The TaskId parameter identifies the current operation and is required when calling the add_menu_item method.

The FolderId parameter contains the item Id of the folder where the context menu was invoked.

The ExistingVerbs parameter contains a list of verbs for menu items already in the menu, separated with the LF character (numeric code 10). This list may include items from the Windows Shell, other Windows Shell extensions, or those added previously by the event handler. The event handler can use the remove_menu_item method to remove any of these existing menu items.

The Flags parameter contains various flags that determine the content and behavior of the menu. The list of valid values for this parameter can be found in the MSDN page for the IContextMenu::QueryContextMenu method under the list of "CFM_* flags".

The ShowNewMenu parameter determines if the "New" submenu should be included in the context menu. This submenu is only automatically included by the Windows Shell inside the context menu for a physical folder. As such, its default value is True for physical items and False for virtual items.

When ShowNewMenu is set by the event handler to True for a virtual folder, the class inserts the New submenu into the context menu. This is done regardless of whether the folder has the SFGAO_READONLY flag in its attributes. The event handler may need to check the attribute and take the flag into account when setting ShowNewMenu.

Note: when a user initiates a context menu for a folder in the left-side tree of File Explorer, the Shell builds a menu and invokes menu-related commands twice - one time with the actual selection, and another time as if no items were selected. If the application sets ShowNewMenu to True on each iteration, the New submenu will be visually duplicated, but clicking on the second submenu will provide no selected items (as this is how this submenu was built). The solution is to add the New menu only when the number of selected items is the one you want (either zero or non-zero, but not both). However, this decision will also affect the New submenu that appears in context menus of the right-side listview.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_move_item Event

This event is fired when an item is moved.

Syntax

class ShellFolderMoveItemEventParams(object):
  @property
  def item_id() -> str: ...

  @property
  def dest_id() -> str: ...

  @property
  def dest_path() -> str: ...

  @property
  def dest_pidl() -> bytes: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_move_item() -> Callable[[ShellFolderMoveItemEventParams], None]: ...
@on_move_item.setter
def on_move_item(event_hook: Callable[[ShellFolderMoveItemEventParams], None]) -> None: ...

Remarks

This event is fired when the Windows Shell needs to move an item.

The ItemId parameter contains the Id of the item that will be moved.

The DestId parameter contains the Id of the new parent item after the move operation is complete. This parameter will be empty if the item is moved outside of the namespace branch managed by the Windows Shell extension, such as to "C:\" or the Desktop folder.

The DestPath parameter contains the destination file path for the moved item. This parameter is only available when DestPIDL denotes a filesystem object.

The DestPIDL parameter contains the destination for the moved item as a PIDL. It will be empty if DestId is set.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

on_rename_item Event

This event is fired when an item is renamed.

Syntax

class ShellFolderRenameItemEventParams(object):
  @property
  def item_id() -> str: ...

  @property
  def new_name() -> str: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class ShellFolder:
@property
def on_rename_item() -> Callable[[ShellFolderRenameItemEventParams], None]: ...
@on_rename_item.setter
def on_rename_item(event_hook: Callable[[ShellFolderRenameItemEventParams], None]) -> None: ...

Remarks

This event is fired when the Windows Shell needs to rename an item.

The ItemId contains the Id of the renamed item.

The NewName parameter contains the new name of the item.

The ResultCode parameter indicates the outcome of the event. By default, its value will always be 0. If the event cannot be handled successfully, its value can be set to an appropriate value to report an error. For example, if no item was found, set ResultCode to CBFSSHELL_ERR_FILE_NOT_FOUND.

Please refer to the Error Codes section for the set of possible values.

If an unhandled exception occurs within the event handler, the class will catch it and report an internal error.

ShellFolder Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

ShellFolder Config Settings

Base Config Settings

ShellFolder Errors

The class uses the following error codes. For convenience, all of these codes are also available as constants.

ShellFolder Errors