ShellFolder Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

callback.CBFSShell.ShellFolder

Remarks

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

The component 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 DisplayName 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, DisplayName, IconLocation, Location, ProxyPath, 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 ListItems event to add items to Windows File Explorer view. Call ListItem 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 ListItem 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 ListItems 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 ListItem 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

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 RegisterSchema once per application installation. Please see Property System for more details.

Columns

The component allows customizing columns in Windows File Explorer view. Handle the GetColumns event, and if the given folder should have columns, call AddColumn once for each column. Your code should make sure that AddColumn 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 AddColumn 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 RegisterSchema once per application installation. Columns linked to custom properties are referred to as dynamic columns and are limited in their capabilities. Please see AddColumn for more information.

Item Information

The application should handle the GetItemId and GetItemInfo events to provide the component 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 component 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 component will handle returning the contents of a file when the item is physical, meaning it contains a value in the FileSystemPath parameter to the ListItem method. No other steps are required in this case.

If no value is provided in FileSystemPath parameter, the component will trigger the GetItemData 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 ListItem method must be set to a non-empty value that is a valid path to an existing file or directory. The component 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 component 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 ListItem 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 ListItem method must be set to empty string.
• Additional handling may be necessary (such as handling of the GetItemData 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 ListItem 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 ListItems event fires. If a folder is not empty, a handler of this event should make one or more calls to the ListItem method to provide information about each item within the folder. When calling ListItem, the Id parameter must be set to a unique identifier. The process used to generate the Id value is outside the scope of the component, 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 ListItem 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 AddColumn and AddIconColumn 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 AddColumn or AddIconColumn. Many properties are predefined in Windows, however custom properties can also be added by creating a .propdesc file and calling RegisterSchema.

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 AddColumn and AddIconColumn.

Property values

When an item's properties are needed (for instance, during a directory listing), the GetProperties event fires. The AddProperty method should be called from within the GetProperties 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 GetColumns event and from the event handler, call the AddColumn or AddIconColumn methods.

Properties Defined By Windows

The AddColumn and AddIconColumn 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 RegisterSchema method is then used to register the custom property defined in the XML file. The UnregisterSchema 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 AddIconColumn 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 component 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 component with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

Attributes Property (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public long Attributes { get; set; }

Public Property Attributes As Long

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

DisplayName Property (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public string DisplayName { get; set; }

Public Property DisplayName As String

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.

DragData Property (ShellFolder Component)

This property contains a collection of items in a drag-n-drop or paste operation.

Syntax

• C#
• VB.NET

public DragItemList DragData { get; }

Public ReadOnly Property DragData As DragItemList

Remarks

This property holds a collection of DragItem objects, which are the data of Drag or Drop operations. The collection is populated before the Drag or Drop event is fired and cleaned when the operation is complete or canceled.

The collection should only be accessed from the event handlers. At other times, it is empty.

This property is read-only and not available at design time.

IconLocation Property (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public string IconLocation { get; set; }

Public Property IconLocation As String

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 (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public string Location { get; set; }

Public Property Location As String

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.

ProxyPath Property (ShellFolder Component)

This property specifies the path to the native proxy DLL.

Syntax

• C#
• VB.NET

public string ProxyPath { get; set; }

Public Property ProxyPath As String

Default Value

""

Remarks

This property may be used to specify the full path with the name of the native proxy DLL, which is loaded by the Windows Shell.

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

Scope Property (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public ShellFolderScopes Scope { get; set; }

enum ShellFolderScopes {
  isAllUsers,
  isCurrentUser
}

Public Property Scope As ShellfolderScopes

Enum ShellFolderScopes
  isAllUsers
  isCurrentUser
End Enum

Default Value

1

Remarks

This property specifies whether the information related to the component 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.

SelectedItems Property (ShellFolder Component)

This property contains a collection of selected Windows Shell items.

Syntax

• C#
• VB.NET

public SelectedItemList SelectedItems { get; }

Public ReadOnly Property SelectedItems As SelectedItemList

Remarks

This property holds a collection of SelectedItem objects, which is populated when the context menu is invoked or clicked.

This property is read-only and not available at design time.

Activate Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void Activate();

Public Sub Activate()

Remarks

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

AddColumn Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void AddColumn(int taskId, string formatId, int propertyId, int flags, string name, int defaultWidth, int viewFlags);

Public Sub AddColumn(ByVal TaskId As Integer, ByVal FormatId As String, ByVal PropertyId As Integer, ByVal Flags As Integer, ByVal Name As String, ByVal DefaultWidth As Integer, ByVal ViewFlags As Integer)

Remarks

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

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the GetColumns 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 RegisterSchema 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 RegisterSchema. 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 RegisterSchema 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

AddIconColumn Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void AddIconColumn(int taskId, string iconSourceProperty, string iconUIProperty);

Public Sub AddIconColumn(ByVal TaskId As Integer, ByVal IconSourceProperty As String, ByVal IconUIProperty As String)

Remarks

This method provides the system with information about an icon column of the folder referenced in the GetColumns event. This method should only be called from within the GetColumns event handler. To add a text column, use AddColumn 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 RegisterSchema 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 AddProperty 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 GetColumns 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.

AddMenuItem Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void AddMenuItem(int taskId, string verb, string parentVerb, string caption, bool isDefault, bool isEnabled);

Public Sub AddMenuItem(ByVal TaskId As Integer, ByVal Verb As String, ByVal ParentVerb As String, ByVal Caption As String, ByVal IsDefault As Boolean, ByVal IsEnabled As Boolean)

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 MergeMenu, MergeMenuTop, and MergeMenuBottom 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 InvokeMenu event.

The ParentVerb parameter is used to create submenus. If set to the verb of a menu item previously added with the AddMenuItem 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

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.

AddProperty Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void AddProperty(int taskId, string formatId, int propertyId, int propType, long numericValue, DateTime dateValue, string stringValue);

Public Sub AddProperty(ByVal TaskId As Integer, ByVal FormatId As String, ByVal PropertyId As Integer, ByVal PropType As Integer, ByVal NumericValue As Long, ByVal DateValue As DateTime, ByVal StringValue As String)

Remarks

This method provides the system with information about a property for an item referenced in the GetProperties event. This method should only be called from within the GetProperties 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 GetProperties 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 GetInfoTip event.

Config Method (ShellFolder Component)

This method sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As String

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void Deactivate();

Public Sub Deactivate()

Remarks

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

HideInfoBar Method (ShellFolder Component)

This method hides a previously shown information bar.

Syntax

• C#
• VB.NET

public void HideInfoBar(string folderId, string infoBarId);

Public Sub HideInfoBar(ByVal FolderId As String, ByVal InfoBarId As String)

Remarks

This method is used to hide an information bar previously shown using the ShowInfoBar method or the GetInfoBar 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 (ShellFolder Component)

This method initializes the core library.

Syntax

• C#
• VB.NET

public void Initialize();

Public Sub Initialize()

Remarks

This method initializes the core library and must be called each time the application starts before attempting to use other component'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 ProxyPath property before calling this method.

Install Method (ShellFolder Component)

This method registers Windows Shell folder information to the system.

Syntax

• C#
• VB.NET

public void Install();

Public Sub Install()

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, DisplayName, IconLocation, Location, ProxyPath, 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

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.

ListItem Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void ListItem(int taskId, string id, long attributes, long size, string displayName, string fileSystemPath, string iconPath, int iconIndex);

Public Sub ListItem(ByVal TaskId As Integer, ByVal Id As String, ByVal Attributes As Long, ByVal Size As Long, ByVal DisplayName As String, ByVal FileSystemPath As String, ByVal IconPath As String, ByVal IconIndex As Integer)

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 ListItems event.

The TaskId parameter identifies the current operation. It should be set to the same value as the one received in the ListItems 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 component.

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 component that an item has no data available for reading. When this value is set, GetItemData 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.

RefreshFolder Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public bool RefreshFolder(string itemId, int action, string newId, int refreshView);

Public Function RefreshFolder(ByVal ItemId As String, ByVal Action As Integer, ByVal NewId As String, ByVal RefreshView As Integer) As Boolean

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 component 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 component events.

If an item or folder is added, this RefreshFolder 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 ListItem method to add a folder. When a new item or folder was or is about to be listed with the ListItem 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 ListItem 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 component 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

RefreshItem Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public bool RefreshItem(string itemId, int action, string newItemId, int refreshView);

Public Function RefreshItem(ByVal ItemId As String, ByVal Action As Integer, ByVal NewItemId As String, ByVal RefreshView As Integer) As Boolean

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 component 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 component events.

ItemId specifies the Id of the item that has changed. This is the Id that an application has previously provided when using the ListItem 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 component 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

RefreshView Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void RefreshView(string itemId, int refreshView);

Public Sub RefreshView(ByVal ItemId As String, ByVal RefreshView As Integer)

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 component to request a refresh of related Windows Shell views. The value can be one of the following:

RegisterSchema Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void RegisterSchema(string fileName);

Public Sub RegisterSchema(ByVal FileName As String)

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 UnregisterSchema.

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.

RemoveMenuItem Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void RemoveMenuItem(int taskId, string verb);

Public Sub RemoveMenuItem(ByVal TaskId As Integer, ByVal Verb As String)

Remarks

This method may be called from within MergeMenu, MergeMenuTop, and MergeMenuBottom 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.

ShowInfoBar Method (ShellFolder Component)

This method shows an information bar for a folder.

Syntax

• C#
• VB.NET

public void ShowInfoBar(string folderId, string infoBarId, string text);

Public Sub ShowInfoBar(ByVal FolderId As String, ByVal InfoBarId As String, ByVal Text As String)

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 (ShellFolder Component)

This method unregisters Windows Shell folder information from the system.

Syntax

• C#
• VB.NET

public void Uninstall();

Public Sub Uninstall()

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

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 components 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 component should be uninstalled properly by calling the corresponding Uninstall method. At the same time, if an application needs to uninstall just one component and keep the other(s), it should call the Uninstall method of that component and then call the Install method of the other components to restore the common information in the shared registry key.

UnregisterSchema Method (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public void UnregisterSchema(string fileName);

Public Sub UnregisterSchema(ByVal FileName As String)

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.

DeleteItem Event (ShellFolder Component)

This event is fired when an item is deleted.

Syntax

• C#
• VB.NET

public event OnDeleteItemHandler OnDeleteItem;

public delegate void OnDeleteItemHandler(object sender, ShellFolderDeleteItemEventArgs e);

public class ShellFolderDeleteItemEventArgs : EventArgs {
  public string ItemId { get; }
  public bool Recycle { get; }
  public int ResultCode { get; set; }
}

Public Event OnDeleteItem As OnDeleteItemHandler

Public Delegate Sub OnDeleteItemHandler(sender As Object, e As ShellFolderDeleteItemEventArgs)

Public Class ShellFolderDeleteItemEventArgs Inherits EventArgs
  Public ReadOnly Property ItemId As String
  Public ReadOnly Property Recycle As Boolean
  Public Property ResultCode As Integer
End Class

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 component will catch it and report an internal error.

Drag Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnDragHandler OnDrag;

public delegate void OnDragHandler(object sender, ShellFolderDragEventArgs e);

public class ShellFolderDragEventArgs : EventArgs {
  public int TaskId { get; }
  public string TargetId { get; }
  public int DragType { get; }
  public int KeyState { get; }
  public int Effects { get; set; }
  public string Formats { get; set; }
  public int ResultCode { get; set; }
}

Public Event OnDrag As OnDragHandler

Public Delegate Sub OnDragHandler(sender As Object, e As ShellFolderDragEventArgs)

Public Class ShellFolderDragEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property TargetId As String
  Public ReadOnly Property DragType As Integer
  Public ReadOnly Property KeyState As Integer
  Public Property Effects As Integer
  Public Property Formats As String
  Public Property ResultCode As Integer
End Class

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 DragData 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 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 component 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 DragData 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 GetDragData 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 component 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 DragData collection will be automatically populated by the component 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.

Drop Event (ShellFolder Component)

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

• C#
• VB.NET

public event OnDropHandler OnDrop;

public delegate void OnDropHandler(object sender, ShellFolderDropEventArgs e);

public class ShellFolderDropEventArgs : EventArgs {
  public int TaskId { get; }
  public string TargetId { get; }
  public int KeyState { get; }
  public int Effects { get; set; }
  public string Formats { get; }
  public int ResultCode { get; set; }
}

Public Event OnDrop As OnDropHandler

Public Delegate Sub OnDropHandler(sender As Object, e As ShellFolderDropEventArgs)

Public Class ShellFolderDropEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property TargetId As String
  Public ReadOnly Property KeyState As Integer
  Public Property Effects As Integer
  Public ReadOnly Property Formats As String
  Public Property ResultCode As Integer
End Class

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 DragData 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 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 component 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 component 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 DragData collection will be automatically populated by the component 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.

Error Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, ShellFolderErrorEventArgs e);

public class ShellFolderErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As ShellFolderErrorEventArgs)

Public Class ShellFolderErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

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

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

GetColumns Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetColumnsHandler OnGetColumns;

public delegate void OnGetColumnsHandler(object sender, ShellFolderGetColumnsEventArgs e);

public class ShellFolderGetColumnsEventArgs : EventArgs {
  public int TaskId { get; }
  public string FolderId { get; }
  public int ResultCode { get; set; }
}

Public Event OnGetColumns As OnGetColumnsHandler

Public Delegate Sub OnGetColumnsHandler(sender As Object, e As ShellFolderGetColumnsEventArgs)

Public Class ShellFolderGetColumnsEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property FolderId As String
  Public Property ResultCode As Integer
End Class

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 AddColumn or AddIconColumn methods from within the handler.

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

The event is fired when items are enumerated using the ListItems event, for each listed folder, right after all items have been reported and after GetProperties was fired for the folder identified by FolderId. For the root folder, the event is fired when the component is activated using the Activate method.

The TaskId parameter identifies the current operation. Its value is required when calling the AddColumn 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 component will catch it and report an internal error.

GetDragData Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetDragDataHandler OnGetDragData;

public delegate void OnGetDragDataHandler(object sender, ShellFolderGetDragDataEventArgs e);

public class ShellFolderGetDragDataEventArgs : EventArgs {
  public int TaskId { get; }
  public int Format { get; }
  public byte[] Buffer { get; }
  public int BytesToRead { get; set; }
  public int ResultCode { get; set; }
}

Public Event OnGetDragData As OnGetDragDataHandler

Public Delegate Sub OnGetDragDataHandler(sender As Object, e As ShellFolderGetDragDataEventArgs)

Public Class ShellFolderGetDragDataEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property Format As Integer
  Public ReadOnly Property Buffer As Byte()
  Public Property BytesToRead As Integer
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired when a drag operation has started within the virtual folder and the component 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 component 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 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 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 component will catch it and report an internal error.

GetInfoBar Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetInfoBarHandler OnGetInfoBar;

public delegate void OnGetInfoBarHandler(object sender, ShellFolderGetInfoBarEventArgs e);

public class ShellFolderGetInfoBarEventArgs : EventArgs {
  public string FolderId { get; }
  public string InfoBarId { get; set; }
  public string Text { get; set; }
}

Public Event OnGetInfoBar As OnGetInfoBarHandler

Public Delegate Sub OnGetInfoBarHandler(sender As Object, e As ShellFolderGetInfoBarEventArgs)

Public Class ShellFolderGetInfoBarEventArgs Inherits EventArgs
  Public ReadOnly Property FolderId As String
  Public Property InfoBarId As String
  Public Property Text As String
End Class

Remarks

This event is fired by the component 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 ShowInfoBar 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.

GetInfoTip Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetInfoTipHandler OnGetInfoTip;

public delegate void OnGetInfoTipHandler(object sender, ShellFolderGetInfoTipEventArgs e);

public class ShellFolderGetInfoTipEventArgs : EventArgs {
  public string ItemId { get; }
  public string InfoTip { get; set; }
}

Public Event OnGetInfoTip As OnGetInfoTipHandler

Public Delegate Sub OnGetInfoTipHandler(sender As Object, e As ShellFolderGetInfoTipEventArgs)

Public Class ShellFolderGetInfoTipEventArgs Inherits EventArgs
  Public ReadOnly Property ItemId As String
  Public Property InfoTip As String
End Class

Remarks

This event is fired by the component 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 AddProperty 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.

GetItemData Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetItemDataHandler OnGetItemData;

public delegate void OnGetItemDataHandler(object sender, ShellFolderGetItemDataEventArgs e);

public class ShellFolderGetItemDataEventArgs : EventArgs {
  public string ItemId { get; }
  public long Start { get; }
  public int Length { get; set; }
  public byte[] Buffer { get; }
  public int ResultCode { get; set; }
}

Public Event OnGetItemData As OnGetItemDataHandler

Public Delegate Sub OnGetItemDataHandler(sender As Object, e As ShellFolderGetItemDataEventArgs)

Public Class ShellFolderGetItemDataEventArgs Inherits EventArgs
  Public ReadOnly Property ItemId As String
  Public ReadOnly Property Start As Long
  Public Property Length As Integer
  Public ReadOnly Property Buffer As Byte()
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component 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.

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 component 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.

GetItemId Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetItemIdHandler OnGetItemId;

public delegate void OnGetItemIdHandler(object sender, ShellFolderGetItemIdEventArgs e);

public class ShellFolderGetItemIdEventArgs : EventArgs {
  public string ParentId { get; }
  public string DisplayName { get; }
  public string ItemId { get; set; }
  public int ResultCode { get; set; }
}

Public Event OnGetItemId As OnGetItemIdHandler

Public Delegate Sub OnGetItemIdHandler(sender As Object, e As ShellFolderGetItemIdEventArgs)

Public Class ShellFolderGetItemIdEventArgs Inherits EventArgs
  Public ReadOnly Property ParentId As String
  Public ReadOnly Property DisplayName As String
  Public Property ItemId As String
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component 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 component will fire the GetItemInfo 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 component will catch it and report an internal error.

GetItemInfo Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetItemInfoHandler OnGetItemInfo;

public delegate void OnGetItemInfoHandler(object sender, ShellFolderGetItemInfoEventArgs e);

public class ShellFolderGetItemInfoEventArgs : EventArgs {
  public string ItemId { get; }
  public long Attributes { get; set; }
  public long Size { get; set; }
  public string DisplayName { get; set; }
  public string FileSystemPath { get; set; }
  public string IconPath { get; set; }
  public int IconIndex { get; set; }
  public int ResultCode { get; set; }
}

Public Event OnGetItemInfo As OnGetItemInfoHandler

Public Delegate Sub OnGetItemInfoHandler(sender As Object, e As ShellFolderGetItemInfoEventArgs)

Public Class ShellFolderGetItemInfoEventArgs Inherits EventArgs
  Public ReadOnly Property ItemId As String
  Public Property Attributes As Long
  Public Property Size As Long
  Public Property DisplayName As String
  Public Property FileSystemPath As String
  Public Property IconPath As String
  Public Property IconIndex As Integer
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired when the component needs to retrieve information about an item. The event will also fire when the RefreshItem method is called and the component 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 component 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 component that an item has no data available for reading. When this value is set, GetItemData 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 component will catch it and report an internal error.

GetNameLimits Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetNameLimitsHandler OnGetNameLimits;

public delegate void OnGetNameLimitsHandler(object sender, ShellFolderGetNameLimitsEventArgs e);

public class ShellFolderGetNameLimitsEventArgs : EventArgs {
  public string FolderId { get; }
  public int MaxLength { get; set; }
  public string AllowedChars { get; set; }
  public string DisallowedChars { get; set; }
}

Public Event OnGetNameLimits As OnGetNameLimitsHandler

Public Delegate Sub OnGetNameLimitsHandler(sender As Object, e As ShellFolderGetNameLimitsEventArgs)

Public Class ShellFolderGetNameLimitsEventArgs Inherits EventArgs
  Public ReadOnly Property FolderId As String
  Public Property MaxLength As Integer
  Public Property AllowedChars As String
  Public Property DisallowedChars As String
End Class

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.

GetProperties Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnGetPropertiesHandler OnGetProperties;

public delegate void OnGetPropertiesHandler(object sender, ShellFolderGetPropertiesEventArgs e);

public class ShellFolderGetPropertiesEventArgs : EventArgs {
  public int TaskId { get; }
  public string ItemId { get; }
  public int ResultCode { get; set; }
}

Public Event OnGetProperties As OnGetPropertiesHandler

Public Delegate Sub OnGetPropertiesHandler(sender As Object, e As ShellFolderGetPropertiesEventArgs)

Public Class ShellFolderGetPropertiesEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property ItemId As String
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component when it needs to retrieve properties of an item. The event is fired for each item listed during the ListItems 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 AddProperty 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 AddProperty 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 component 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 component. This ensures that the component can properly fire the GetItemData event when the item is copied or accessed. This is done by adding a property using AddProperty 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);

InvokeMenu Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnInvokeMenuHandler OnInvokeMenu;

public delegate void OnInvokeMenuHandler(object sender, ShellFolderInvokeMenuEventArgs e);

public class ShellFolderInvokeMenuEventArgs : EventArgs {
  public string Verb { get; }
  public string FolderId { get; }
}

Public Event OnInvokeMenu As OnInvokeMenuHandler

Public Delegate Sub OnInvokeMenuHandler(sender As Object, e As ShellFolderInvokeMenuEventArgs)

Public Class ShellFolderInvokeMenuEventArgs Inherits EventArgs
  Public ReadOnly Property Verb As String
  Public ReadOnly Property FolderId As String
End Class

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 SelectedItems 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 MergeMenuTop 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

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

ListItems Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnListItemsHandler OnListItems;

public delegate void OnListItemsHandler(object sender, ShellFolderListItemsEventArgs e);

public class ShellFolderListItemsEventArgs : EventArgs {
  public int TaskId { get; }
  public string ParentId { get; }
  public int Flags { get; }
  public int ResultCode { get; set; }
}

Public Event OnListItems As OnListItemsHandler

Public Delegate Sub OnListItemsHandler(sender As Object, e As ShellFolderListItemsEventArgs)

Public Class ShellFolderListItemsEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property ParentId As String
  Public ReadOnly Property Flags As Integer
  Public Property ResultCode As Integer
End Class

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 ListItem method should be called within the handler for each individual item and subfolder that will be in the folder.

The GetProperties event will fire for each of the listed items. Following this, the GetColumns event and then the GetNameLimits event will sequentially fire for each of the listed folders.

The TaskId parameter identifies the current operation and is required when calling the ListItem 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 component will catch it and report an internal error.

MergeMenu Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnMergeMenuHandler OnMergeMenu;

public delegate void OnMergeMenuHandler(object sender, ShellFolderMergeMenuEventArgs e);

public class ShellFolderMergeMenuEventArgs : EventArgs {
  public int TaskId { get; }
  public string FolderId { get; }
  public string ExistingVerbs { get; }
  public int Flags { get; }
  public int ResultCode { get; set; }
}

Public Event OnMergeMenu As OnMergeMenuHandler

Public Delegate Sub OnMergeMenuHandler(sender As Object, e As ShellFolderMergeMenuEventArgs)

Public Class ShellFolderMergeMenuEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property FolderId As String
  Public ReadOnly Property ExistingVerbs As String
  Public ReadOnly Property Flags As Integer
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component 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 SelectedItems property.

To handle the event properly, an event handler must call the AddMenuItem 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 AddMenuItem 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 RemoveMenuItem 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 RemoveMenuItem 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 component 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: MergeMenu for the initial ordering, MergeMenuBottom for adding items to the bottom, and MergeMenuTop 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..

MergeMenuBottom Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnMergeMenuBottomHandler OnMergeMenuBottom;

public delegate void OnMergeMenuBottomHandler(object sender, ShellFolderMergeMenuBottomEventArgs e);

public class ShellFolderMergeMenuBottomEventArgs : EventArgs {
  public int TaskId { get; }
  public string FolderId { get; }
  public string ExistingVerbs { get; }
  public int Flags { get; }
  public int ResultCode { get; set; }
}

Public Event OnMergeMenuBottom As OnMergeMenuBottomHandler

Public Delegate Sub OnMergeMenuBottomHandler(sender As Object, e As ShellFolderMergeMenuBottomEventArgs)

Public Class ShellFolderMergeMenuBottomEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property FolderId As String
  Public ReadOnly Property ExistingVerbs As String
  Public ReadOnly Property Flags As Integer
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component 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 SelectedItems property.

To handle the event properly, an event handler must call the AddMenuItem 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 AddMenuItem 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 RemoveMenuItem 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 RemoveMenuItem 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 component will catch it and report an internal error.

MergeMenuTop Event (ShellFolder Component)

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

Syntax

• C#
• VB.NET

public event OnMergeMenuTopHandler OnMergeMenuTop;

public delegate void OnMergeMenuTopHandler(object sender, ShellFolderMergeMenuTopEventArgs e);

public class ShellFolderMergeMenuTopEventArgs : EventArgs {
  public int TaskId { get; }
  public string FolderId { get; }
  public string ExistingVerbs { get; }
  public int Flags { get; }
  public bool ShowNewMenu { get; set; }
  public int ResultCode { get; set; }
}

Public Event OnMergeMenuTop As OnMergeMenuTopHandler

Public Delegate Sub OnMergeMenuTopHandler(sender As Object, e As ShellFolderMergeMenuTopEventArgs)

Public Class ShellFolderMergeMenuTopEventArgs Inherits EventArgs
  Public ReadOnly Property TaskId As Integer
  Public ReadOnly Property FolderId As String
  Public ReadOnly Property ExistingVerbs As String
  Public ReadOnly Property Flags As Integer
  Public Property ShowNewMenu As Boolean
  Public Property ResultCode As Integer
End Class

Remarks

This event is fired by the component 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 SelectedItems property.

To handle the event properly, an event handler must call the AddMenuItem 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 AddMenuItem 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 RemoveMenuItem 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 physical items. As such, its default value is true for physical items and false for virtual 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 component will catch it and report an internal error.

MoveItem Event (ShellFolder Component)

This event is fired when an item is moved.

Syntax

• C#
• VB.NET

public event OnMoveItemHandler OnMoveItem;

public delegate void OnMoveItemHandler(object sender, ShellFolderMoveItemEventArgs e);

public class ShellFolderMoveItemEventArgs : EventArgs {
  public string ItemId { get; }
  public string DestId { get; }
  public string DestPath { get; }
  public byte[] DestPIDL { get; }
  public int ResultCode { get; set; }
}

Public Event OnMoveItem As OnMoveItemHandler

Public Delegate Sub OnMoveItemHandler(sender As Object, e As ShellFolderMoveItemEventArgs)

Public Class ShellFolderMoveItemEventArgs Inherits EventArgs
  Public ReadOnly Property ItemId As String
  Public ReadOnly Property DestId As String
  Public ReadOnly Property DestPath As String
  Public ReadOnly Property DestPIDL As Byte()
  Public Property ResultCode As Integer
End Class

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 component will catch it and report an internal error.

RenameItem Event (ShellFolder Component)

This event is fired when an item is renamed.

Syntax

• C#
• VB.NET

public event OnRenameItemHandler OnRenameItem;

public delegate void OnRenameItemHandler(object sender, ShellFolderRenameItemEventArgs e);

public class ShellFolderRenameItemEventArgs : EventArgs {
  public string ItemId { get; }
  public string NewName { get; }
  public int ResultCode { get; set; }
}

Public Event OnRenameItem As OnRenameItemHandler

Public Delegate Sub OnRenameItemHandler(sender As Object, e As ShellFolderRenameItemEventArgs)

Public Class ShellFolderRenameItemEventArgs Inherits EventArgs
  Public ReadOnly Property ItemId As String
  Public ReadOnly Property NewName As String
  Public Property ResultCode As Integer
End Class

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 component will catch it and report an internal error.

DragItem Type

Represents a data item in a drag-n-drop or paste operation.

Remarks

This type represents a data item that is a part of a drag-n-drop or a copy/paste operation.

Data in these operations is represented in one or several formats, with each format having a numeric identifier and an optional name. Each data item belongs to some format. Data in different formats may be one element or a list of elements. The Format and Index fields together specify from which format and list the item comes.

Fields

SelectedItem Type

Represents a selected Windows Shell item.

Remarks

This type represents a Windows Shell item in the list of items selected in ShellMenu.

Fields

Config Settings (ShellFolder Component)

ShellFolder Config Settings

Base Config Settings

Trappable Errors (ShellFolder Component)

ShellFolder Errors