TortoiseOverlays ================ Introduction: ------------- Windows only has a limited amount of free slots for icon overlay handlers (around 12 - the rest is used by the system itself). This is a problem for Tortoise clients because they usually need a lot of those handlers to show the different states of files and folders. If a user has more than one Tortoise client installed, that's already enough to hit the system limit and some overlays won't show up anymore. The purpose of the TortoiseOverlays project is to provide a common icon overlay handler for all the Tortoise clients. This reduces the risk of hitting the system limit. The only downside is that all Tortoise clients will have the very same overlay icons, which means the users won't immediately see from the overlays which version control system is handling a certain folder of file. But this is still far better than not be able to show an overlay at all because of the system limit. Using the TortoiseOverlays dll: ------------------------------- Usually, an icon overlay handler is registered under HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\explorer\ShellIconOverlayIdentifiers To make use of the TortoiseOverlays dll, register your overlay handler under HKLM\Software\TortoiseOverlays\\Statusname, with 'Statusname' being one of: Normal under version control, but nothing special Modified locally modified, needs committing/pushing Conflict requires user interaction to solve a problem Deleted item is missing or deleted ReadOnly item is readonly, can't be edited Locked user has permission to edit item (has exclusive lock) Added item is added, but not yet in the repository Ignored item is ignored by the version control system Unversioned item is not under version control The difference here is that TortoiseOverlays must know which one of your overlay handlers handles which of the states so it can show the correct icon. An example: instead of creating the registry key HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\explorer\ShellIconOverlayIdentifiers\TortoiseSVNNormal with the "(default)" registry value being the GUID, create the key HKLM\Software\TortoiseOverlays\\Normal and add a string value "SVN"="GUID" That's it. No more changes are needed. How it works: ------------- TortoiseOverlays registers itself with the explorer to handle the nine states mentioned above, i.e. it registers nine overlay handlers. The explorer process initializes the TortoiseOverlays handler, calling its IShellIconOverlayIdentifier::GetOverlayInfo(). TortoiseOverlays looks for the registered overlay handlers under HKLM\Software\TortoiseOverlays\\Statusname and calls their GetOverlayInfo() method so they can initialize too (Note that any change to the icon name, index, ... your handler does are overwritten later and won't be used - it's TortoiseOverlays that handles the icons now). After the initialization, TortoiseOverlays relays every call to its IShellIconOverlayIdentifier::IsMemberOf() method to the other handlers. The first handler that returns S_OK determines whether the icon is shown or not. Since TortoiseOverlays is shared between all Tortoise clients (it's a so called shared component) it installs in c:\program files\common files (%commonprogramfiles%) to make sure it's available from all clients. How to install/redistribute TortoiseOverlays: --------------------------------------------- You can either install TortoiseOverlays with the provided merge module (which is the recommended way, because it can properly handle the required reference counting of the registry keys and dlls), or use the also provided msi installer. You MUST NOT try to install the dll and create the registry keys yourself! If you have a non-msi installer, you can call the msi installer like this: msiexec /i TortoiseOverlays-1.0.0.XXXX-win32.msi /qn /norestart But in that case, you also must not deinstall it when your client gets deinstalled. The reason I chose merge modules/msi is that TortoiseOverlays is a *shared* component, and other setup packages can't handle reference counting very well. And removing TortoiseOverlays with your client even though some other Tortoise client still needs it is not acceptable. Using custom icons: ------------------- TortoiseOverlays comes with a default set of icons. But if you like to give the user the chance to use his own preferred icon set, you can tell TortoiseOverlays to use a different set. To do that, create the following registry values and set them to the paths of your icons: HKCU\Software\TortoiseOverlays\NormalIcon HKCU\Software\TortoiseOverlays\ModifiedIcon HKCU\Software\TortoiseOverlays\ConflictIcon HKCU\Software\TortoiseOverlays\DeletedIcon HKCU\Software\TortoiseOverlays\ReadOnlyIcon HKCU\Software\TortoiseOverlays\LockedIcon HKCU\Software\TortoiseOverlays\AddedIcon HKCU\Software\TortoiseOverlays\IgnoredIcon HKCU\Software\TortoiseOverlays\UnversionedIcon Make sure you install your new icon sets under c:\program files\common files\TortoiseOverlays\icons\iconsetname (%commonprogramfiles%\TortoiseOverlays\icons\iconsetname) to avoid missing icons as soon as your client gets uninstalled. Because as the TortoiseOverlays dll your icon sets are shared files, shared between all Tortoise clients. Also make sure your icon sets include *all* icons, not just the ones your client uses. Otherwise the user will have inconsistent icons in those clients who use all icons.