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

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

Installation

Defining File Masks

Initialization and Activation

Displaying Overlay Icons

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

Property List

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

Method List

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

Event List

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

Config Settings

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

ExcludeMasks Property (ShellOverlays Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExcludeMasks();
int SetExcludeMasks(const char* lpszExcludeMasks);

Unicode (Windows)
LPWSTR GetExcludeMasks();
INT SetExcludeMasks(LPCWSTR lpszExcludeMasks);

char* cbfsshell_shelloverlays_getexcludemasks(void* lpObj);
int cbfsshell_shelloverlays_setexcludemasks(void* lpObj, const char* lpszExcludeMasks);

QString GetExcludeMasks();
int SetExcludeMasks(QString qsExcludeMasks);

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

Data Type

String

IncludeMasks Property (ShellOverlays Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetIncludeMasks();
int SetIncludeMasks(const char* lpszIncludeMasks);

Unicode (Windows)
LPWSTR GetIncludeMasks();
INT SetIncludeMasks(LPCWSTR lpszIncludeMasks);

char* cbfsshell_shelloverlays_getincludemasks(void* lpObj);
int cbfsshell_shelloverlays_setincludemasks(void* lpObj, const char* lpszIncludeMasks);

QString GetIncludeMasks();
int SetIncludeMasks(QString qsIncludeMasks);

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

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

Data Type

String

OverlayIcons Property (ShellOverlays Class)

Contains a collection of overlay icon information.

Syntax

• C++
• C
• Qt

CBFSShellList<CBFSShellOverlayIcon>* GetOverlayIcons();

int cbfsshell_shelloverlays_getoverlayiconscount(void* lpObj);

int cbfsshell_shelloverlays_getoverlayiconenabled(void* lpObj, int overlayiconindex);
int cbfsshell_shelloverlays_setoverlayiconenabled(void* lpObj, int overlayiconindex, int bOverlayIconEnabled);

int cbfsshell_shelloverlays_getoverlayiconiconindex(void* lpObj, int overlayiconindex);
int cbfsshell_shelloverlays_setoverlayiconiconindex(void* lpObj, int overlayiconindex, int iOverlayIconIconIndex);

char* cbfsshell_shelloverlays_getoverlayiconiconpath(void* lpObj, int overlayiconindex);
int cbfsshell_shelloverlays_setoverlayiconiconpath(void* lpObj, int overlayiconindex, const char* lpszOverlayIconIconPath);

int cbfsshell_shelloverlays_getoverlayiconpriority(void* lpObj, int overlayiconindex);
int cbfsshell_shelloverlays_setoverlayiconpriority(void* lpObj, int overlayiconindex, int iOverlayIconPriority);

int GetOverlayIconsCount();

bool GetOverlayIconEnabled(int iOverlayIconIndex);
int SetOverlayIconEnabled(int iOverlayIconIndex, bool bOverlayIconEnabled);

int GetOverlayIconIconIndex(int iOverlayIconIndex);
int SetOverlayIconIconIndex(int iOverlayIconIndex, int iOverlayIconIconIndex);

QString GetOverlayIconIconPath(int iOverlayIconIndex);
int SetOverlayIconIconPath(int iOverlayIconIndex, QString qsOverlayIconIconPath);

int GetOverlayIconPriority(int iOverlayIconIndex);
int SetOverlayIconPriority(int iOverlayIconIndex, int iOverlayIconPriority);

Remarks

This property holds a collection of OverlayIcon objects. Due to system constraints, this collection is pre-populated and limited to ten (10) items. which can be disabled or enabled by an application.

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

Data Type

CBFSShellOverlayIcon

ProxyPath Property (ShellOverlays Class)

Specifies the path to the native proxy DLL.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyPath();
int SetProxyPath(const char* lpszProxyPath);

Unicode (Windows)
LPWSTR GetProxyPath();
INT SetProxyPath(LPCWSTR lpszProxyPath);

char* cbfsshell_shelloverlays_getproxypath(void* lpObj);
int cbfsshell_shelloverlays_setproxypath(void* lpObj, const char* lpszProxyPath);

QString GetProxyPath();
int SetProxyPath(QString qsProxyPath);

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

Data Type

String

Activate Method (ShellOverlays Class)

This method makes overlay icons available to the system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Activate();

Unicode (Windows)
INT Activate();

int cbfsshell_shelloverlays_activate(void* lpObj);

int Activate();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Config Method (ShellOverlays Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cbfsshell_shelloverlays_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Deactivate Method (ShellOverlays Class)

Stops monitoring changes.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Deactivate();

Unicode (Windows)
INT Deactivate();

int cbfsshell_shelloverlays_deactivate(void* lpObj);

int Deactivate();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Initialize Method (ShellOverlays Class)

Initializes the core library.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Initialize();

Unicode (Windows)
INT Initialize();

int cbfsshell_shelloverlays_initialize(void* lpObj);

int Initialize();

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 ProxyPath property before calling this method.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Install Method (ShellOverlays Class)

Registers icon overlay information in the system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Install();

Unicode (Windows)
INT Install();

int cbfsshell_shelloverlays_install(void* lpObj);

int Install();

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Uninstall Method (ShellOverlays Class)

Unregisters icon overlays from the system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Uninstall();

Unicode (Windows)
INT Uninstall();

int cbfsshell_shelloverlays_uninstall(void* lpObj);

int Uninstall();

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

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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Error Event (ShellOverlays Class)

Fires when an unhandled error occurs during an event.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(ShellOverlaysErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} ShellOverlaysErrorEventParams;


Unicode (Windows)
virtual INT FireError(ShellOverlaysErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} ShellOverlaysErrorEventParams;

#define EID_SHELLOVERLAYS_ERROR 1

virtual INT CBFSSHELL_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class ShellOverlaysErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(ShellOverlaysErrorEventParams *e);

// Or, subclass ShellOverlays and override this emitter function.
virtual int FireError(ShellOverlaysErrorEventParams *e) {...}

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.

UseIcon Event (ShellOverlays Class)

Fires when the Windows Shell queries for overlay icons.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireUseIcon(ShellOverlaysUseIconEventParams *e);

typedef struct {
  int IconNumber;
  const char *FilePath;
  int Attributes;
  int Apply;
  int reserved;
} ShellOverlaysUseIconEventParams;


Unicode (Windows)
virtual INT FireUseIcon(ShellOverlaysUseIconEventParams *e);

typedef struct {
  INT IconNumber;
  LPCWSTR FilePath;
  INT Attributes;
  BOOL Apply;
  INT reserved;
} ShellOverlaysUseIconEventParams;

#define EID_SHELLOVERLAYS_USEICON 2

virtual INT CBFSSHELL_CALL FireUseIcon(INT &iIconNumber, LPWSTR &lpszFilePath, INT &iAttributes, BOOL &bApply);

class ShellOverlaysUseIconEventParams {
public:
  int IconNumber();

  const QString &FilePath();

  int Attributes();

  bool Apply();
  void SetApply(bool bApply);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void UseIcon(ShellOverlaysUseIconEventParams *e);

// Or, subclass ShellOverlays and override this emitter function.
virtual int FireUseIcon(ShellOverlaysUseIconEventParams *e) {...}

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

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

OverlayIcon Type

Represents an overlay icon.

Syntax

CBFSShellOverlayIcon (declared in cbfsshell.h)

Remarks

This type represents an overlay icon exposed to the Windows Shell by the class.

An icon is enabled when both the Enabled field is set to true and IconIndex and IconPath fields are set to appropriate values.

• Enabled
• IconIndex
• IconPath
• Priority

Fields

CBFSShellList Type

Syntax

CBFSShellList<T> (declared in cbfsshell.h)

Remarks

CBFSShellList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the ShellOverlays class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (ShellOverlays Class)

ShellOverlays Config Settings

Base Config Settings

Trappable Errors (ShellOverlays Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ShellOverlays Errors