Struct cbfsshell::ShellOverlays

Properties   Methods   Events   Config Settings   Errors  

The ShellOverlays struct 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 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.

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

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

 
 Copy
// 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.

 
 Copy
m_Overlays.Initialize();
m_Overlays.Activate();

Displaying Overlay Icons

While the struct 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.

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

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

 
 Copy
m_Overlays.Uninstall();

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintainted by CBFSShell. Due to this, the ShellOverlays struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of ShellOverlays when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

exclude_masks property (ShellOverlays Struct)

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

Syntax

fn exclude_masks(&self ) -> Result<String, CBFSShellError> 
fn set_exclude_masks(&self, value : &str) ->  Option<CBFSShellError> 
fn set_exclude_masks_ref(&self, value : &String) ->  Option<CBFSShellError> 

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

C#
 Copy
// Exclude any .txt files from receiving an overlay icon
m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\*.txt";

Example (Multiple masks):

C#
 Copy
// 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.

Data Type

String

include_masks property (ShellOverlays Struct)

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

Syntax

fn include_masks(&self ) -> Result<String, CBFSShellError> 
fn set_include_masks(&self, value : &str) ->  Option<CBFSShellError> 
fn set_include_masks_ref(&self, value : &String) ->  Option<CBFSShellError> 

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

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.

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

C#
 Copy
// Allow any .txt files to receive overlay icons
m_Overlays.ExcludeMasks = "C:\\Users\\User\\Documents\\*.txt";

Example (Multiple masks):

C#
 Copy
// 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 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.

Data Type

String

overlay_icons_count property (ShellOverlays Struct)

The number of records in the OverlayIcon arrays.

Syntax

fn overlay_icons_count(&self ) -> Result<i32, CBFSShellError> 

Default Value

0

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.

Data Type

i32

overlay_icon_enabled property (ShellOverlays Struct)

Specifies that an overlay icon is enabled.

Syntax

fn overlay_icon_enabled(&self , OverlayIconIndex : i32) -> Result<bool, CBFSShellError> 
fn set_overlay_icon_enabled(&self, OverlayIconIndex : i32, value : bool) ->  Option<CBFSShellError> 

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

overlay_icon_icon_index property (ShellOverlays Struct)

The index of the icon within the file.

Syntax

fn overlay_icon_icon_index(&self , OverlayIconIndex : i32) -> Result<i32, CBFSShellError> 
fn set_overlay_icon_icon_index(&self, OverlayIconIndex : i32, value : i32) ->  Option<CBFSShellError> 

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

i32

overlay_icon_icon_path property (ShellOverlays Struct)

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

Syntax

fn overlay_icon_icon_path(&self , OverlayIconIndex : i32) -> Result<String, CBFSShellError> 
fn set_overlay_icon_icon_path(&self, OverlayIconIndex : i32, value : &str) ->  Option<CBFSShellError> 
fn set_overlay_icon_icon_path_ref(&self, OverlayIconIndex : i32, value : &String) ->  Option<CBFSShellError> 

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

overlay_icon_priority property (ShellOverlays Struct)

The priority of the icon.

Syntax

fn overlay_icon_priority(&self , OverlayIconIndex : i32) -> Result<i32, CBFSShellError> 
fn set_overlay_icon_priority(&self, OverlayIconIndex : i32, value : i32) ->  Option<CBFSShellError> 

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

i32

proxy_path property (ShellOverlays Struct)

Specifies the path to the native proxy DLL.

Syntax

fn proxy_path(&self ) -> Result<String, CBFSShellError> 
fn set_proxy_path(&self, value : &str) ->  Option<CBFSShellError> 
fn set_proxy_path_ref(&self, value : &String) ->  Option<CBFSShellError> 

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

This method makes overlay icons available to the system.

Syntax

fn activate(&self) -> Result<(), CBFSShellError>

Remarks

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

config method (ShellOverlays Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, CBFSShellError>

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

Stops monitoring changes.

Syntax

fn deactivate(&self) -> Result<(), CBFSShellError>

Remarks

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

initialize method (ShellOverlays Struct)

Initializes the core library.

Syntax

fn initialize(&self) -> Result<(), CBFSShellError>

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

install method (ShellOverlays Struct)

Registers icon overlay information in the system.

Syntax

fn install(&self) -> Result<(), CBFSShellError>

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 () error.

uninstall method (ShellOverlays Struct)

Unregisters icon overlays from the system.

Syntax

fn uninstall(&self) -> Result<(), CBFSShellError>

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 () 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.

on_error event (ShellOverlays Struct)

Fires when an unhandled error occurs during an event.

Syntax

// ShellOverlaysErrorEventArgs carries the ShellOverlays Error event's parameters.
pub struct ShellOverlaysErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// ShellOverlaysErrorEvent defines the signature of the ShellOverlays Error event's handler function.
pub trait ShellOverlaysErrorEvent {
  fn on_error(&self, sender : ShellOverlays, e : &mut ShellOverlaysErrorEventArgs);
}

impl <'a> ShellOverlays<'a> {
  pub fn on_error(&self) -> &'a dyn ShellOverlaysErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn 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.

on_use_icon event (ShellOverlays Struct)

Fires when the Windows Shell queries for overlay icons.

Syntax

// ShellOverlaysUseIconEventArgs carries the ShellOverlays UseIcon event's parameters.
pub struct ShellOverlaysUseIconEventArgs {
  fn icon_number(&self) -> i32
  fn file_path(&self) -> &String
  fn attributes(&self) -> i32
  fn apply(&self) -> bool
  fn set_apply(&self, value : bool)
}

// ShellOverlaysUseIconEvent defines the signature of the ShellOverlays UseIcon event's handler function.
pub trait ShellOverlaysUseIconEvent {
  fn on_use_icon(&self, sender : ShellOverlays, e : &mut ShellOverlaysUseIconEventArgs);
}

impl <'a> ShellOverlays<'a> {
  pub fn on_use_icon(&self) -> &'a dyn ShellOverlaysUseIconEvent;
  pub fn set_on_use_icon(&mut self, value : &'a dyn 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 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 struct has no control over this decision.

Example:

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

 
 Copy
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 Struct)

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

ShellOverlays Errors