ShellOverlays Class

Properties Methods Events Config Settings Errors

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

Syntax

class cbfsshell.ShellOverlays

Remarks

The ShellOverlays class 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 class will be the one to display over the particular shell item.

The class 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 class is to configure the icons that File Explorer should display. The overlay_icons 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 class 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 include_masks and exclude_masks properties. The include_masks property specifies which files and folders are eligible for overlays. exclude_masks 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 class is active, the on_use_icon 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 class with short descriptions. Click on the links for further details.


exclude_masks	Specifies one or more path masks used to exclude files and folders from receiving overlay icons.
include_masks	Specifies one or more path masks that define which files and folders are eligible for overlay icons.
overlay_icons_count	The number of records in the OverlayIcon arrays.
overlay_icon_enabled	Specifies that an overlay icon is enabled.
overlay_icon_icon_index	The index of the icon within the file.
overlay_icon_icon_path	An absolute name with path of a file with the icon.
overlay_icon_priority	The priority of the icon.
proxy_path	Specifies the path to the native proxy DLL.

Method List

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


activate	This method makes overlay icons available to the system.
config	Sets or retrieves a configuration setting.
deactivate	Stops monitoring changes.
initialize	Initializes the core library.
install	Registers icon overlay information in the system.
uninstall	Unregisters icon overlays from the system.

Event List

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


on_error	Fires when an unhandled error occurs during an event.
on_use_icon	Fires when the Windows Shell queries for overlay icons.

Config Settings

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


IconSetName	A human-readable name of the overlay icon set.
IPCFormat	The fixed name of the RPC endpoint.
IsInstalled	Specifies whether the installation was performed.
ProductGUID	ID of the proxy DLL.
ServerStartArguments	The arguments to pass with the command.
ServerStartCommandLine	The command line to run when the server is not available.
ServerStartOperation	The operation verb.
ServerStartShowOption	Defines how the application windows should be shown.
ServerStartTimeToWait	Optional time to wait before retrying RPC connection.
ServerStartWorkingDirectory	The working directory.
BuildInfo	Information about the product's build.
LicenseInfo	Information about the current license.

exclude_masks property

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

Syntax

def get_exclude_masks() -> str: ...
def set_exclude_masks(value: str) -> None: ...

exclude_masks = property(get_exclude_masks, set_exclude_masks)

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 on_use_icon event will not fire for it, and the class 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 include_masks and exclude_masks 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 include_masks before it is checked against exclude_masks. The on_use_icon event will only fire for the file or directory if it matches the inclusion masks in include_masks and does not match the exclusion masks in exclude_masks. This way, exclusion masks override the result of inclusion masks.

include_masks property

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

Syntax

def get_include_masks() -> str: ...
def set_include_masks(value: str) -> None: ...

include_masks = property(get_include_masks, set_include_masks)

Default Value

Remarks

This property is used to filter files and folders that should receive overlay icons. When set, the on_use_icon event will only fire for files and folders that match the specified masks. If empty, the on_use_icon 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

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

overlay_icons_count property

The number of records in the OverlayIcon arrays.

Syntax

def get_overlay_icons_count() -> int: ...

overlay_icons_count = property(get_overlay_icons_count, None)

Default Value

Remarks

This property controls the size of the following arrays:

overlay_icon_enabled
overlay_icon_icon_index
overlay_icon_icon_path
overlay_icon_priority

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

This property is read-only.

overlay_icon_enabled property

Specifies that an overlay icon is enabled.

Syntax

def get_overlay_icon_enabled(overlay_icon_index: int) -> bool: ...
def set_overlay_icon_enabled(overlay_icon_index: int, value: bool) -> None: ...

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 overlay_icon_index parameter specifies the index of the item in the array. The size of the array is controlled by the overlay_icons_count property.

overlay_icon_icon_index property

The index of the icon within the file.

Syntax

def get_overlay_icon_icon_index(overlay_icon_index: int) -> int: ...
def set_overlay_icon_icon_index(overlay_icon_index: int, value: int) -> None: ...

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 overlay_icon_index parameter specifies the index of the item in the array. The size of the array is controlled by the overlay_icons_count property.

overlay_icon_icon_path property

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

Syntax

def get_overlay_icon_icon_path(overlay_icon_index: int) -> str: ...
def set_overlay_icon_icon_path(overlay_icon_index: int, value: str) -> None: ...

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 overlay_icon_index parameter specifies the index of the item in the array. The size of the array is controlled by the overlay_icons_count property.

overlay_icon_priority property

The priority of the icon.

Syntax

def get_overlay_icon_priority(overlay_icon_index: int) -> int: ...
def set_overlay_icon_priority(overlay_icon_index: int, value: int) -> None: ...

Default Value

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 overlay_icon_index parameter specifies the index of the item in the array. The size of the array is controlled by the overlay_icons_count property.

proxy_path property

Specifies the path to the native proxy DLL.

Syntax

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

proxy_path = property(get_proxy_path, set_proxy_path)

Default Value

Remarks

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

A directory path containing proxy DLLs. For example: C:\Users\User\Documents\CBFS Shell 2024\proxy. In this case, the class will automatically choose the first DLL with the appropriate architecture.
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 class will automatically choose the first DLL that matches the specified pattern.

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

activate method

This method makes overlay icons available to the system.

Syntax

def activate() -> None: ...

Remarks

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

config method

Sets or retrieves a configuration setting.

Syntax

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

Remarks

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

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

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

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

deactivate method

Stops monitoring changes.

Syntax

def deactivate() -> None: ...

Remarks

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

initialize method

Initializes the core library.

Syntax

def initialize() -> None: ...

Remarks

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

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

install method

Registers icon overlay information in the system.

Syntax

def install() -> None: ...

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 overlay_icons collection. Each icon, if used, should have its fields defined. Also, you may change the default value of the proxy_path 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

Unregisters icon overlays from the system.

Syntax

def uninstall() -> None: ...

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 classes

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

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

on_error event

Fires when an unhandled error occurs during an event.

Syntax

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

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

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

Remarks

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

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

on_use_icon event

Fires when the Windows Shell queries for overlay icons.

Syntax

class ShellOverlaysUseIconEventParams(object):
  @property
  def icon_number() -> int: ...

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

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

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

# In class ShellOverlays:
@property
def on_use_icon() -> Callable[[ShellOverlaysUseIconEventParams], None]: ...
@on_use_icon.setter
def on_use_icon(event_hook: Callable[[ShellOverlaysUseIconEventParams], None]) -> None: ...

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 overlay_icons 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 class 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

ShellOverlays Config Settings

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

ShellOverlays Config Settings

IconSetName: A human-readable name of the overlay icon set.

This configuration setting is used to specify a human-readable name of the set of icons when the icon-related records are written in the registry. The name acts as a prefix, to which the icon number is added. Adjust this setting before calling the install method. If not set, a license-id-based value is constructed and used during the installation.

IPCFormat: The fixed name of the RPC endpoint.

If the Windows Shell and the server operate in different desktop sessions, set this configuration before installing the native proxy DLL.

IsInstalled: Specifies whether the installation was performed.

This configuration setting returns True if the class finds the required registry entries, put there by a previous call to the install method; otherwise, False is returned. In the latter case, an application should use the install method again.

ProductGUID: ID of the proxy DLL.

A product GUID (also known as project ID) is used to distinguish among various installations performed by different applications.

ServerStartArguments: The arguments to pass with the command.