Custom icons for Win32 starpacks

As of 2003-02-09, the SDX "wrap" command supports generating Win32 starpacks which have a custom icon for the executable.

This took some hacking, but first - here's how to do it:

• say you have a area "myapp.vfs/" which you want to turn into a "myapp.exe"
• you need a Windows "ICO" file with the following resolution icons in it:

        16x16, 4-bit (16-color)
        16x16, 8-bit (256-color)
        32x32, 4-bit (16-color)
        32x32, 8-bit (256-color)
        48x48, 4-bit (16-color)
        48x48, 8-bit (256-color)

• put that icon in the file myapp.vfs/tclkit.ico
• now generate a starpack as usual, i.e:

        sdx wrap myapp.exe -runtime tclkit.exe

SDX wrap will see the "tclkit.ico" file at the root level of the starkit (it gets included in VFS, like everything else), and if the runtime is a Win32 executable it'll do some string replaces to overwrite the ICO resource of the generated starpack.

There are a number of comments to make:

• your icon file has to be placed in the root, and it has to be called "tclkit.ico"
• the "-runtime" file you use has to have a ".exe" file suffix to trigger SDX
• that runtime file has to be a tclkit with a suitable original "tclkit.ico" in its VFS runtime
• in other words: you need a Tclkit release built on or after 2003-02-09
• you need *all* of the above 6 resolutions/depths of your icon, if you want to be certain that your icon gets shown instead of the original Tk one, regardless of windows version, screen settings, and resolution (if nothing else you can take another one and stretch/shrink it, for example with MSVC6)
• the resulting starpack will contain the new tclkit.ico files as part of its VFS runtime
• note that this works cross-platform: sdx can customize icons for .exe's while wrapping from any platform

That's it. It's all done beneath the surface. All icon substitions done by SDX are reported on stdout.

How SDX replaces icons in Starpacks

The logic behind all this is a bit convoluted. To work, SDX deals with three icons:

1. the icon resource in the original runtime
2. the tclkit.ico file in the VFS section of the original runtime
3. the new myapp.vfs/tclkit.ico file

What SDX then does for each icon resolution it finds in #2, is take the bitmap, search for it in #1, and do s atring replace with the corresponding resolution bitmap from #3.

So the essential trick to make this work is that the runtime with which a starpack is constructed must contain the same icons twice - once as Windows resource, somewhere inside the executable, and once as "original" tclkit.ico in the VFS at the end of that executable.

It's all done as a string search + replace. That way SDX does not need to understand executable file formats, nor exactly how icon files are structured (only enough to locate each icon resolution).

SDX assumes that bitmaps of icons with a specific resolution always use the same number of bytes. It will only replace a bitmap with another one of the same size.

To make SDX customize icons for executables other than tclkit.exe, that runtime must be set up in the same way as tclkit:

• all icon resolutions it wants to support must already be present
• whatever icon it uses as default must be stored as "tclkit.ico" copy in its VFS section