ShellOverlays Component

Properties   Methods   Events   Config Settings   Errors  

The ShellOverlays class enables adding overlay icons over any files and folders displayed by the Windows Shell.

Syntax

cbfsshell.ShellOverlays

Remarks

The ShellOverlays struct provides a simple way to add overlay icons over file and folder icons in File Explorer.

The system image list for overlay icons is limited to 16 icons, of which four (4) are used by the Windows Shell, leaving just 12 icons for applications. Cloud synchronization applications, version control system clients (SmartSVN, SmartGit, Tortoise SVN and Tortoise Git, etc.) and other software products each register multiple overlay icons. So, it is not guaranteed that an overlay icon set in the struct will be the one to display over the particular shell item.

The struct pre-registers ten (10) overlay icons for one license and lets the application use any number of them, disabling the unused icons so that they do not get in the way of other applications.

Configuring Overlay Icons

The first step in using the struct is to configure the icons that File Explorer should display. The OverlayIcons collection is automatically prepopulated with ten icon slots your application can use to define overlay icons. Each slot represents an icon that can be registered with the system. To configure an icon in a slot, set the IconPath property to specify the file that contains the icon, set the IconIndex property to indicate its index within that file, and enable it by setting Enabled to true. import callback.CBFSShell; ShellOverlays m_Overlays = new ShellOverlays(); // Only configure the first icon in the 'OverlayIcons' collection OverlayIcon icon = m_Overlays.OverlayIcons[0]; // The path to a file that contains your icons. This can point to an .exe, .dll, or .ico file. icon.IconPath = "C:\\PATH\\TO\\ICON\\FILE.ico"; // The index of the icon in that .dll file icon.IconIndex = 1; // This must be set to true for the icon to be visible in File Explorer icon.Enabled = true;

Installation

Next, call the Install method. This will load a proxy dynamic link library (DLL) into File Explorer to facilitate communication with the Windows Shell. In addition, this will prompt the struct to register the configured overlay icons to the Windows Registry. Installation should be done at least once before using the library on a new system, but it may be done several times to update the desired icon configurations. m_Overlays.Install();

Defining File Masks

After installation, specify which files and folders are candidates for receiving overlay icons by using the IncludeMasks and ExcludeMasks properties. The IncludeMasks property specifies which files and folders are eligible for overlays. ExcludeMasks can override these selections. // Only consider overlays for .txt files in the "Documents" folder m_Overlays.IncludeMasks = "C:\\Users\\User\\Documents\\*.txt"; // Exclude any files named "test.txt" from receiving an overlay icon m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\test.txt";

Initialization and Activation

Once the overlay icons and file masks are configured, call the Initialize method to perform necessary setup tasks. Then, call the Activate method to start processing Windows Shell requests and display the overlay icons. m_Overlays.Initialize(); m_Overlays.Activate();

Displaying Overlay Icons

While the struct is active, the UseIcon event will fire for each file and folder that matches the previously defined file masks. This event is fired just before an item is displayed in File Explorer, providing your application with an opportunity to decide whether a candidate overlay icon should be applied.

When the event is fired, the FilePath parameter contains the full path of the file or folder being evaluated, and the Attributes parameter provides its file system attributes. In addition, the IconNumber parameter identifies which candidate overlay icon from the prepopulated OverlayIcons collection is being considered. Initially, the Use parameter is set to false. If your application determines that the overlay icon should be applied to the item, simply enable the icon by setting Use to true. m_Overlays.OnUseIcon += (sender, e) => { // Identifies the candidate overlay icon from the OverlayIcons collection. var iconNumber = e.IconNumber; // The full path of the file or folder being evaluated. var filePath = e.FilePath; // File system attributes of the file or folder. var attributes = e.Attributes; // Display overlay icon 0 for the current file or folder if (e.IconNumber == 0) { e.Use = true; } }; Once the Use parameter is set to true, the overlay icons should be visible in File Explorer on top of any files or folders the event was fired for.

Deactivation and Uninstall

To stop serving overlay icons while still keeping your configuration intact, call the Deactivate method. m_Overlays.Deactivate(); To unregister the overlay icons from the Windows Registry, call the Uninstall method. This action will also unregister the proxy DLL from File Explorer, which typically is performed when the application should be removed from the system. m_Overlays.Uninstall();

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.

ExcludeMasks Property (ShellOverlays Component)

Specifies one or more path masks used to exclude files and folders from receiving overlay icons.

Syntax

func (obj *ShellOverlays) ExcludeMasks() (string, error)
func (obj *ShellOverlays) SetExcludeMasks(value string) error

Default Value

""

Remarks

This property is used to prevent overlay icons from appearing over specific files and folders. If a file or folder matches any of the specified masks, the UseIcon event will not fire for it, and the struct will inform the Windows Shell that its overlay icons should not be applied.

A mask may contain any combination of valid file name characters and wildcards (the * and ? characters). Multiple mask values should be separated with the LF character (numeric code 10).

Example (Single mask): // Exclude any .txt files from receiving an overlay icon m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\*.txt";

Example (Multiple masks): // Exclude the following files from receiving overlay icons: // 1) Files named "test.txt" that are located in the 'C:\Users\User\Documents\ directory // 2) Files named "test2.txt" that are located in the 'C:\Content\' directory m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\test.txt" + "\x0a" + // LF character marks the start of a new mask "C:\\Content\\test2.txt";

Combining Inclusion and Exclusion Masks

The IncludeMasks and ExcludeMasks properties may be used together or separately. When both properties are set, the name of the file or directory being evaluated by the Windows Shell must first match IncludeMasks before it is checked against ExcludeMasks. The UseIcon event will only fire for the file or directory if it matches the inclusion masks in IncludeMasks and does not match the exclusion masks in ExcludeMasks. This way, exclusion masks override the result of inclusion masks.

Data Type

string

IncludeMasks Property (ShellOverlays Component)

Specifies one or more path masks that define which files and folders are eligible for overlay icons.

Syntax

func (obj *ShellOverlays) IncludeMasks() (string, error)
func (obj *ShellOverlays) SetIncludeMasks(value string) error

Default Value

""

Remarks

This property is used to filter files and folders that should receive overlay icons. When set, the UseIcon event will only fire for files and folders that match the specified masks. If empty, the UseIcon will fire for all files and folders queried by the Windows Shell when they are about to be displayed in File Explorer.

Combining Inclusion and Exclusion Masks

The IncludeMasks and ExcludeMasks properties may be used together or separately. When both properties are set, the name of the file or directory being evaluated by the Windows Shell must first match IncludeMasks before it is checked against ExcludeMasks. The UseIcon event will only fire for the file or directory if it matches the inclusion masks in IncludeMasks and does not match the exclusion masks in ExcludeMasks. This way, exclusion masks override the result of inclusion masks.

A mask may contain any combination of valid file name characters and wildcards (the * and ? characters). Multiple mask values should be separated with the LF character (numeric code 10).

Example (Single mask): // Allow any .txt files to receive overlay icons m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\*.txt";

Example (Multiple masks): // Include the following files from receiving overlay icons: // 1) Files named "test.txt" that are located in the 'C:\Users\User\Documents\ directory // 2) Files named "test2.txt" that are located in the 'C:\Content\' directory m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\test.txt" + "\x0a" + // LF character marks the start of a new mask "C:\\Content\\test2.txt";

Combining Inclusion and Exclusion Masks

The IncludeMasks and ExcludeMasks properties may be used together or separately. When both properties are set, the name of the file or directory being evaluated by the Windows Shell must first match IncludeMasks before it is checked against ExcludeMasks. The UseIcon event will only fire for the file or directory if it matches the inclusion masks in IncludeMasks and does not match the exclusion masks in ExcludeMasks. This way, exclusion masks override the result of inclusion masks.

Data Type

string

OverlayIconsCount Property (ShellOverlays Component)

The number of records in the OverlayIcon arrays.

Syntax

func (obj *ShellOverlays) OverlayIconsCount() (int32, error)

Default Value

0

Remarks

This property controls the size of the following arrays:

• OverlayIconEnabled
• OverlayIconIconIndex
• OverlayIconIconPath
• OverlayIconPriority

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

This property is read-only.

Data Type

int32

OverlayIconEnabled Property (ShellOverlays Component)

Specifies that an overlay icon is enabled.

Syntax

func (obj *ShellOverlays) OverlayIconEnabled(OverlayIconIndex int32) (bool, error)
func (obj *ShellOverlays) SetOverlayIconEnabled(OverlayIconIndex int32, value bool) error

Default Value

false

Remarks

Specifies that an overlay icon is enabled.

This field specifies whether the overlay icon is enabled and can be used.

The OverlayIconIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OverlayIconsCount property.

Data Type

bool

OverlayIconIconIndex Property (ShellOverlays Component)

The index of the icon within the file.

Syntax

func (obj *ShellOverlays) OverlayIconIconIndex(OverlayIconIndex int32) (int32, error)
func (obj *ShellOverlays) SetOverlayIconIconIndex(OverlayIconIndex int32, value int32) error

Default Value

-1

Remarks

The index of the icon within the file.

This field determines which icon is displayed for the item when the IconPath field contains a path to an EXE or DLL file. Its value should be the index of the specific icon within the resources of the DLL or EXE file in IconPath.

Set this field to -1 if the file referenced by the IconPath field specifies a file with just one icon.

The OverlayIconIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OverlayIconsCount property.

Data Type

int32

OverlayIconIconPath Property (ShellOverlays Component)

An absolute name with path of a file with the icon.

Syntax

func (obj *ShellOverlays) OverlayIconIconPath(OverlayIconIndex int32) (string, error)
func (obj *ShellOverlays) SetOverlayIconIconPath(OverlayIconIndex int32, value string) error

Default Value

""

Remarks

An absolute name with path of a file with the icon.

This field should be set to the path of a file that contains an icon. Together with the IconIndex field, this value tells the Windows Shell which icon to display. If the file contains just one icon, set IconIndex to -1.

The Windows Shell supports loading of overlay icons from EXE, DLL, and ICO files.

The OverlayIconIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OverlayIconsCount property.

Data Type

string

OverlayIconPriority Property (ShellOverlays Component)

The priority of the icon.

Syntax

func (obj *ShellOverlays) OverlayIconPriority(OverlayIconIndex int32) (int32, error)
func (obj *ShellOverlays) SetOverlayIconPriority(OverlayIconIndex int32, value int32) error

Default Value

0

Remarks

The priority of the icon.

The priority is used by the Windows Shell to determine which of the icon to display when several overlay icons are available for an item.

Note: The Windows Shell has internal rules to determine overlay icon priority. The value of this field only acts as a hint for the cases when these rules do not apply.

The acceptable values are from 0 to 100, with 0 recommended for all cases.

The OverlayIconIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OverlayIconsCount property.

Data Type

int32

ProxyPath Property (ShellOverlays Component)

Specifies the path to the native proxy DLL.

Syntax

func (obj *ShellOverlays) ProxyPath() (string, error)
func (obj *ShellOverlays) SetProxyPath(value string) error

Default Value

""

Remarks

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

1. A directory path containing proxy DLLs. For example: C:\Users\User\Documents\CBFS Shell 2024\proxy. In this case, the struct will automatically choose the first DLL with the appropriate architecture.
2. A full file path with wildcards in the filename. For example C:\Users\User\Documents\CBFS Shell 2024\proxy\CBFSShell.*.x64. In this case, the struct will automatically choose the first DLL that matches the specified pattern.

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

Data Type

string

Activate Method (ShellOverlays Component)

This method makes overlay icons available to the system.

Syntax

func (obj *ShellOverlays) Activate() error

Remarks

Use this method to make the overlay icons available to the system.

Config Method (ShellOverlays Component)

Sets or retrieves a configuration setting.

Syntax

func (obj *ShellOverlays) Config(ConfigurationString string) (string, error)

Remarks

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

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

Stops monitoring changes.

Syntax

func (obj *ShellOverlays) Deactivate() error

Remarks

Use this method to stop monitoring for changes and unregister as an observer of change notifications.

Initialize Method (ShellOverlays Component)

Initializes the core library.

Syntax

func (obj *ShellOverlays) Initialize() error

Remarks

This method initializes the core library and must be called each time the application starts before attempting to use other struct'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 (ShellOverlays Component)

Registers icon overlay information in the system.

Syntax

func (obj *ShellOverlays) Install() error

Remarks

This method is used to install the native proxy DLL that integrates with the Windows Shell and register the icon overlay information in the system.

Before calling this method, the application should set up the values of the items of the OverlayIcons collection. Each icon, if used, should have its fields defined. Also, you may change the default value of the ProxyPath property and the IconSetName configuration setting, which are used during installation.

The registration information for overlay icons is written to the registry for all users. Due to this, 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.

Uninstall Method (ShellOverlays Component)

Unregisters icon overlays from the system.

Syntax

func (obj *ShellOverlays) Uninstall() error

Remarks

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

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

Registry Scope and User Permissions

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

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

Handling multiple structs

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

Error Event (ShellOverlays Component)

Fires when an unhandled error occurs during an event.

Syntax

// ShellOverlaysErrorEventArgs carries the ShellOverlays Error event's parameters.
type ShellOverlaysErrorEventArgs struct {...}

func (args *ShellOverlaysErrorEventArgs) ErrorCode() int32
func (args *ShellOverlaysErrorEventArgs) Description() string
// ShellOverlaysErrorEvent defines the signature of the ShellOverlays Error event's handler function.
type ShellOverlaysErrorEvent func(sender *ShellOverlays, args *ShellOverlaysErrorEventArgs)

func (obj *ShellOverlays) GetOnErrorHandler() ShellOverlaysErrorEvent
func (obj *ShellOverlays) SetOnErrorHandler(handlerFunc ShellOverlaysErrorEvent)

Remarks

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

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

UseIcon Event (ShellOverlays Component)

Fires when the Windows Shell queries for overlay icons.

Syntax

// ShellOverlaysUseIconEventArgs carries the ShellOverlays UseIcon event's parameters.
type ShellOverlaysUseIconEventArgs struct {...}

func (args *ShellOverlaysUseIconEventArgs) IconNumber() int32
func (args *ShellOverlaysUseIconEventArgs) FilePath() string
func (args *ShellOverlaysUseIconEventArgs) Attributes() int32
func (args *ShellOverlaysUseIconEventArgs) Apply() bool
func (args *ShellOverlaysUseIconEventArgs) SetApply(value bool)

// ShellOverlaysUseIconEvent defines the signature of the ShellOverlays UseIcon event's handler function.
type ShellOverlaysUseIconEvent func(sender *ShellOverlays, args *ShellOverlaysUseIconEventArgs)

func (obj *ShellOverlays) GetOnUseIconHandler() ShellOverlaysUseIconEvent
func (obj *ShellOverlays) SetOnUseIconHandler(handlerFunc ShellOverlaysUseIconEvent)

Remarks

This event fires when the Windows Shell requests overlay icons for a file or folder about to be displayed in File Explorer. The event provides an opportunity to determine whether a candidate overlay icon should be a applied to the file or folder the event was fired for.

To handle the event properly, an application may first use the FilePath and Attributes parameters to identify the file or folder the event was fired for. Then, it can determine if the icon identified by IconNumber should be displayed over it. The application can then set Apply to true to display the icon, or to false to skip it.

IconNumber represents the index of the icon in the OverlayIcons collection. Its value may be used to determine whether this icon should be applied to the file or folder the event was fired for.

FilePath specifies the full path of the file or folder being evaluated. This value may be used alongside Attributes to determine if the specified file or folder should receive the overlay icon identified by IconNumber.

Attributes contains the file system attributes of the file or folder being evaluated. For the full list of attributes, please see Microsoft documentation. This value may be used alongside FilePath to determine if the specified file or folder should receive the overlay icon identified by IconNumber.

Apply indicates whether the overlay icon should be applied to the item. This value should be set to true to display the icon for the file or folder identified by FilePath and Attributes. By default, this value is set to false.

If multiple registered overlay icons are to be used, the Windows Shell has internal rules to decide which one will be applied, and the struct has no control over this decision.

Example: m_Overlays.OnUseIcon += (sender, e) => { // Identifies the candidate overlay icon from the OverlayIcons collection. var iconNumber = e.IconNumber; // The full path of the file or folder being evaluated. var filePath = e.FilePath; // File system attributes of the file or folder. var attributes = e.Attributes; // Display overlay icon 0 for a specific file if (filePath.Equals("C:\\Users\\User\\Documents\\test.txt") && e.IconNumber == 0) { e.Use = true; } };

UI Considerations

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

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

Config Settings (ShellOverlays Component)

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

ShellOverlays Config Settings

Base Config Settings

Trappable Errors (ShellOverlays Component)

ShellOverlays Errors