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.