Rick Strahl's Weblog  

Wind, waves, code and everything in between...
.NET • C# • Markdown • JavaScript • Angular
Contact   •   Articles   •   Products   •   Support   •   Advertise
Sponsored by:
West Wind WebSurge - Rest Client and Http Load Testing for Windows

Using custom icons in a compiled HTML Help 1.0 (CHM) file

On this page:
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">

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):

<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">

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:


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.

The Voices of Reason


April 27, 2005

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

wow.. thanks for this site! i was able to customize the icons with the help of this... :)

November 23, 2005

# .chm file with parameters

Can i give parameters for finding any particular sentance to .chm file

May 08, 2006

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

In order to avoid using system's user folder I succeed using this kind or relative path to system root.

"file://%systemroot%\..\Program Files\Company\Application\images\helpicons.bmp"

Note that this solution doesn't support localization for "Program Files". I tried to use %programfiles% but it fails.

This solution will also fail if user chooses to install your application in other volume other than the system (D:,E:,F:,...).

Rick Strahl
May 08, 2006

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

Right, that's why that's not really a good solution. WinDir is a stable location as is SystemRoot as long as you don't make any assumptions beyond that.

May 15, 2006

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

I would like a relative path to the .chm file location. Is that possible?

Rick Strahl
May 15, 2006

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

Nope - not possible as far as I know and I've looked around for some time. Only paths available is %WinDir% and %SystemRoot%.

May 15, 2006

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

URL path is also possible !

June 20, 2007

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

Hi Rick,

Seems the above discussion is highly relevant for me. But I am not able to make it work. Infact I have some e-books. Some in PDF format and others in CHM format. When I Use view-> Thumbnails, PDF files show the Title Image, whereas in case of .chm files there is no image even though the image is there when we open the .chm file. I want to use the image as thumbnail. Is it possible through the method discussed above.


# Adobe - RoboHelp for HTMLHelp

Todd Morrow
September 16, 2008

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

Where in the system can I find the default icon strip?

Mike Macliver
August 31, 2011

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

Thanks Rick, very useful web page.

Q. Do you know if it's possible to change the icons of the .chm toolbar buttons?


Rick Strahl
August 31, 2011

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

@Mike - no you can't change the buttons. There are options that cause a few buttons to render or not render but you can't change the layout or change the actual buttons.

Brian Ekins
February 24, 2012

# re: Using custom icons in a compiled HTML Help 1.0 (CHM) file

Thanks for this information. Too bad it doesn't work as you would expect. I was trying to get my custom icons to work and am running into a problem. I came to the web looking for help but after reading about the issues you've described I'm just going to put up with the default icons.

West Wind  © Rick Strahl, West Wind Technologies, 2005 - 2023