I see this question all the time and I've dealt with this for a number of my applications over the years, so I'd thought I address this here.
Help Builder also allows creation of custom icon strips automatically and notifies you of the issues involved.
Let's review the issue first. A CHM help file by default contains a set of standard icons that are part of the HTML Help engine. This icon strip is made up of 42 default icons which usually are used in pairs of twos. The first of the two is the closed icon the second is the 'open' icon. So for all intents and purposes there are really only 21 icons available.
The default icon strip looks like this:
You can choose any of these images in your Help File, which map to a topic ID. To change the icon in Workshop:
-
Go to the Content tab and select your topic
-
Select the properties for the topic (the pencil icon)
-
Click advanced and change the Image index
This allows you to change the basic icon for each topic involved.
In the underlying Help Project files this maps to an entry in the Content file (.hhc) and looks like this for an individual entry:
<LI> <OBJECT type="text/sitemap">
<param name="Name" value="West Wind HTML Help Builder">
<param name="Local" value="INDEXPAGE.htm">
<param name="ImageNumber" value="3">
</OBJECT>
The ImageNumber is what determines the icon used. Note this number is 0 based so 3 actually is the 4th image.
Using a custom Icon Strip
You can also use external icon files although Microsoft (in their infinite wisdom) did not provide a way to compile the external icon strip right into the help file and use it. Instead you have to link the external strip externally.
As it turns out this is a lousy mechanism because you need to know a fully qualified path to the icon file and the CHM engine provides no easy way to know what directory the CHM file lives in.
The only way I've found to do this is to reference the icon file externally in the Windows directory or a directory relative to it because there is a %systemroot% environment variable that can be used to specify the path to the icon file.
You put this into your HHC file before the content (see object tag below):
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
</HEAD><BODY>
<OBJECT type="text/site properties">
<param name="ImageList" value="file://%systemroot%\helpbuildericons.bmp">
<param name="Image Width" value="16">
<param name="Color Mask" value="0xff00ff">
</OBJECT>
You can also set this in Help Workshop in the Table of Contents dialog with the following options:
Go to the project options dialog (Properties Icon)
Select Use custom image file
Set the Image File
Set the width of each icon (16 pixels usually)
For the image file you'd use:
%systemroot%\helpbuildericons.bmp
which translates to the Windows directory and the HelpBuilderIcons.bmp file. Here's an example of what my custom developer style icon file looks like:
Now, in order to get this to work you need to make sure that when you deploy your help file you copy the icon file into this directory. Alternately (and what I often do for this) is to create a HelpIcons directory below the Windows path and drop them in there to keep it separate, but that's really up to you.
Before you go off wildly creating custom icons, understand that the icon formats are very, very delicate. Specifically the icons are limted to the 8 basic Windows colors. Yes you read that right - 8 colors. So you will have to be pretty creative to create nice looking icons in 16 pixels and 8 colors <g>. Most of the above were pulled from other applications and then reduces in colors in Paint Shop Pro. It worked well with some not so well with others. Editing this strip is also a pain in the ass as you might expect. I used cut and paste to do this originally.
In fact it was so much of a pain in the ass that I added support for icon adding and replacement to Help Builder where you can now select the icon and simply import a new image from a GIF,BMP,JPG,PNG etc. and embed it into the strip. This addresses the layout issue, but you still need to make sure that your original images follow the 8 color guidelines that the CHM engine works with. If you do this I suggest you check your work immediately to make sure the icons render properly.
Incidentally HTML Help 2.0 doesn't do any better and in fact I would recommend using custom icons as it will clash with other MSDN or VS.NET style help content it gets merged with.
The CHM 1.0 format is a mess and riddled with problems. Microsoft has done us all a disfavor by never fixing the base problems of this format always in anticipation of something new that would succeed it. CHM was introduced in the late 90's and now 8 years later we're still working with this mess. The overall concept is nice but the problems with the help compiler and worse the engine itself could have all been fixed but the Help team at Microsoft has been too arrogant to fix these known bugs for many years. Pretty sad scene.
Other Posts you might also like