src/TortoiseOverlays/Documentation.txt

   1 TortoiseOverlays\r
   2 ================\r
   3 \r
   4 Introduction:\r
   5 -------------\r
   6 Windows only has a limited amount of free slots for icon overlay\r
   7 handlers (around 12 - the rest is used by the system itself). This is\r
   8 a problem for Tortoise clients because they usually need a lot of those\r
   9 handlers to show the different states of files and folders. If a user\r
  10 has more than one Tortoise client installed, that's already enough to\r
  11 hit the system limit and some overlays won't show up anymore.\r
  12 \r
  13 The purpose of the TortoiseOverlays project is to provide a common icon\r
  14 overlay handler for all the Tortoise clients. This reduces the risk of\r
  15 hitting the system limit. The only downside is that all Tortoise clients\r
  16 will have the very same overlay icons, which means the users won't\r
  17 immediately see from the overlays which version control system is \r
  18 handling a certain folder of file. But this is still far better than\r
  19 not be able to show an overlay at all because of the system limit.\r
  20 \r
  21 Using the TortoiseOverlays dll:\r
  22 -------------------------------\r
  23 Usually, an icon overlay handler is registered under\r
  24 HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\explorer\ShellIconOverlayIdentifiers\r
  25 To make use of the TortoiseOverlays dll, register your overlay handler\r
  26 under HKLM\Software\TortoiseOverlays\\Statusname, with 'Statusname'\r
  27 being one of:\r
  28 Normal             under version control, but nothing special\r
  29 Modified           locally modified, needs committing/pushing\r
  30 Conflict           requires user interaction to solve a problem\r
  31 Deleted            item is missing or deleted\r
  32 ReadOnly           item is readonly, can't be edited\r
  33 Locked             user has permission to edit item (has exclusive lock)\r
  34 Added              item is added, but not yet in the repository\r
  35 Ignored            item is ignored by the version control system\r
  36 Unversioned        item is not under version control\r
  37 \r
  38 The difference here is that TortoiseOverlays must know which one of your\r
  39 overlay handlers handles which of the states so it can show the correct\r
  40 icon. An example:\r
  41 instead of creating the registry key\r
  42 HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\explorer\ShellIconOverlayIdentifiers\TortoiseSVNNormal\r
  43 with the "(default)" registry value being the GUID, create the key\r
  44 HKLM\Software\TortoiseOverlays\\Normal\r
  45 and add a string value "SVN"="GUID"\r
  46 \r
  47 That's it. No more changes are needed.\r
  48 \r
  49 How it works:\r
  50 -------------\r
  51 TortoiseOverlays registers itself with the explorer to handle the nine\r
  52 states mentioned above, i.e. it registers nine overlay handlers.\r
  53 The explorer process initializes the TortoiseOverlays handler, calling\r
  54 its IShellIconOverlayIdentifier::GetOverlayInfo(). TortoiseOverlays \r
  55 looks for the registered overlay handlers under \r
  56 HKLM\Software\TortoiseOverlays\\Statusname and calls their \r
  57 GetOverlayInfo() method so they can initialize too (Note that any change\r
  58 to the icon name, index, ... your handler does are overwritten later\r
  59 and won't be used - it's TortoiseOverlays that handles the icons now).\r
  60 After the initialization, TortoiseOverlays relays every call to its\r
  61 IShellIconOverlayIdentifier::IsMemberOf() method to the other handlers.\r
  62 The first handler that returns S_OK determines whether the icon is shown\r
  63 or not.\r
  64 \r
  65 Since TortoiseOverlays is shared between all Tortoise clients (it's a\r
  66 so called shared component) it installs in \r
  67 c:\program files\common files (%commonprogramfiles%) to make sure it's\r
  68 available from all clients.\r
  69 \r
  70 How to install/redistribute TortoiseOverlays:\r
  71 ---------------------------------------------\r
  72 You can either install TortoiseOverlays with the provided merge module\r
  73 (which is the recommended way, because it can properly handle the \r
  74 required reference counting of the registry keys and dlls), or use the\r
  75 also provided msi installer.\r
  76 You MUST NOT try to install the dll and create the registry keys yourself!\r
  77 If you have a non-msi installer, you can call the msi installer like this:\r
  78 msiexec /i TortoiseOverlays-1.0.0.XXXX-win32.msi /qn /norestart\r
  79 But in that case, you also must not deinstall it when your client gets\r
  80 deinstalled.\r
  81 \r
  82 The reason I chose merge modules/msi is that TortoiseOverlays is a \r
  83 *shared* component, and other setup packages can't handle reference \r
  84 counting very well. And removing TortoiseOverlays with your client even\r
  85 though some other Tortoise client still needs it is not acceptable.\r
  86 \r
  87 \r
  88 Using custom icons:\r
  89 -------------------\r
  90 TortoiseOverlays comes with a default set of icons. But if you like to\r
  91 give the user the chance to use his own preferred icon set, you can\r
  92 tell TortoiseOverlays to use a different set. To do that, create the\r
  93 following registry values and set them to the paths of your icons:\r
  94 HKCU\Software\TortoiseOverlays\NormalIcon\r
  95 HKCU\Software\TortoiseOverlays\ModifiedIcon\r
  96 HKCU\Software\TortoiseOverlays\ConflictIcon\r
  97 HKCU\Software\TortoiseOverlays\DeletedIcon\r
  98 HKCU\Software\TortoiseOverlays\ReadOnlyIcon\r
  99 HKCU\Software\TortoiseOverlays\LockedIcon\r
 100 HKCU\Software\TortoiseOverlays\AddedIcon\r
 101 HKCU\Software\TortoiseOverlays\IgnoredIcon\r
 102 HKCU\Software\TortoiseOverlays\UnversionedIcon\r
 103 \r
 104 Make sure you install your new icon sets under \r
 105 c:\program files\common files\TortoiseOverlays\icons\iconsetname\r
 106 (%commonprogramfiles%\TortoiseOverlays\icons\iconsetname)\r
 107 to avoid missing icons as soon as your client gets uninstalled. Because\r
 108 as the TortoiseOverlays dll your icon sets are shared files, shared\r
 109 between all Tortoise clients.\r
 110 Also make sure your icon sets include *all* icons, not just the ones\r
 111 your client uses. Otherwise the user will have inconsistent icons in\r
 112 those clients who use all icons.