Starting with HTML Help

.

Environment: This demo is made with MS Visual C++ Version 6.0 with the latest Service Pack. It does NOT work under earlier versions of MSVC++.

One day I woke up and found myself wanting HTML Help in my project. So I started searching for docs on using it with MFC and found out that it wasn't as simple as I thought. All I wanted was one entry in the Help menu (Help Topics...) and a Help button in each dialog which would bring up the corresponding topic. And a nice contents pane in the Help of course so users could get a quick overview and easily navigate through Help.

For those of you who want to get started with HTML Help my explorations might be useful. For those of you who know of better or more ways to use it: let the world (and me!) know. For those of you who think "What in the world is HTML Help?" look at the Help in Internet Explorer 4.01 and you'll know.

Using HTML Help splits up in a few sections. On each of which I'll tell you the way I'm doing it.

Installing the HTML Help Authoring Kit

You can download the latest version for free here. I'll assume you install it in C:\Program Files\HTML Help Workshop. After installing you should prepare DevStudio: go to Tools, Options, Directories, then:

  • Under Show directories for choose Include files, click on New and type
    C:\Program Files\HTML Help Workshop\include
  • Under Show directories for choose Library files, click on New and type
    C:\Program Files\HTML Help Workshop\lib
  • Under Show directories for choose Executable files, click on New and type
    C:\Program Files\HTML Help Workshop
  • Close DevStudio and restart to save the changes.

Creating the topic files in HTML language

First, of course, you'll have to create the .htm topic files themselves. I like WYSIWIG on this so I am using Frontpage Explorer to create a web which will contain all of the files. Besides the .htm files you can add images, avi's, sounds, just about anything you want to use. The help file later on will behave like a website. You can also use one of Frontpage's themes if you want.

I do use a theme but I do not use the navigation features of Frontpage. The resulting buttons on each page take up to much space in the Help window. Besides that, I make use of the contents pane of the HTML Help. Navigating through a Help file by means of a Table of Contents pane is, in my humble opinion, much more clear to the user than criss-cross navigation with buttons on each page (when you use a theme you should add each .htm page to the navigation pane (all on the same level) and rename it. The themes use these names then for the page titles).

Under your project main directory create a directory called HTML. In HTML create a directory called Web. Publish the Frontpage web you've created to Web. Frontpage puts all sorts of files in here but the HTML Help Compiler will only include the files you and the pages you made refer to so don't bother about that.

Making the help file (.chm) itself

Start HTML Help Workshop, click on New, Project, Next. Browse to the HTML directory, type yourname, click Open, Next, Next, Finish. Click on Add/Remove Topic Files, Add, and browse to the Web directory. Select all the .htm files you've created and click Open, OK. Click on HTML Api Information, Header File and type yourname.hm. This will become the file with context ID's from the project. Ignore the warning from HTML Help Workshop and include the file anyway. Click on OK. By now you should have added a [FILES] section with the topic files and a [MAP] section with the header file in it.

There are many other things you can do. I've included a complete published web in the demo project so feel free to look into the HTML Help project file.

Creating a MFC project

When you create a MFC project with AppWizard you can choose for Context Sensitive Help. When you do this there will be a hlp directory in your project's main directory and a MakeHelp.bat. You won't need any of these files for HTML Help so leave the Context Sensitive Help unchecked.

The HTML Help Project has to be added to your project, just like the old WinHelp project. Quite a bit of manual changes to the project settings I'm afraid. Start with adding the HTML Help Project File: from DevStudio's menu choose Project, Add To Project, Files. Browse to the HTML directory, select the .hhp file and click OK. Now you can change the settings for your project. From the menu choose Project, Settings, All Configurations. Then make the following changes:

Setting for: Field/Button: Type:
Link tab Object/library modules htmlhelp.lib
yourname.hhp
(Custom Build tab)
Description Making HTML Help File...
  Commands hhc.exe html\$(InputName).hhp
echo.
copy html\$(InputName).chm $(OutDir)\$(InputName).chm
  Outputs html\$(InputName).chm
  Dependencies... html\$(TargetName).hm
Resource.h
(Custom Build tab)
Description Making HTML Help Include File...
  Commands makehm ID_,IDH_,0x10000 IDM_,IDH_,0x10000 resource.h >>"html\$(TargetName).hm"
makehm IDP_,IDH_,0x30000 resource.h >>"html\$(TargetName).hm"
makehm IDR_,IDH_,0x20000 resource.h >>"html\$(TargetName).hm"
makehm IDD_,IDH_,0x20000 resource.h >>"html\$(TargetName).hm"
makehm IDW_,IDH_,0x50000 resource.h >>"html\$(TargetName).hm"
echo. >>"html\$(TargetName).hm"
MakeIDH "html\$(TargetName).hm"
  Outputs html\$(TargetName).hm

and click on OK. Finally add the statement #include <htmlhelp.h> to your stdafx.h.

Comments on the custom build command for resource.h

I make use of the utility MAKEHM that comes with MSVC. It creates a file with renumbered ID's corresponding to the resource IDs in your RESOURCE.H. When you create a project with AppWizard and switch the Context Sensitive Help on you'll get a MAKEHELP.BAT file which calls MAKEHM and creates a .hm file with all your resource ID's mapped to another value in lines like HIDR_MAINFRAME 0x20080.

For some reason the gurus at Microsoft decided to do it differently in HTML Help. Somewhere in the MSDN docs I found the note "If you used the IDH_ prefix for your context-sensitive help topic IDs, HTML Help Workshop automatically compares the topic IDs in your compiled help file against those mapped to numeric values in your project file. Compiler messages will tell you where your context-sensitive help is broken so you can fix it." That's the reason I use IDH_ as a prefix only. The custom build command creates lines like IDH_MAINFRAME 0x20080.

Another decision the MS gurus made is that this wasn't good enough for HTML Help. There must be a #define in front of the ID. That's why I wrote a small utility named MAKEIDH. You'll find it in the main directory of the demo project. It parses a file and places #define in front of every line that starts with IDH_. Final result for the .hm file: #define IDH_MAINFRAME 0x20080. Copy the utility MAKEIDH.EXE to a subdirectory anywhere in your path to have it always available.

Implementing help calls

By now your project should compile without errors. There are a few changes to do in the source files. First, in InitInstance(), change the default file extension for the help file from .hlp to .chm:

    // Change extension for help file
    CString strHelpFile = m_pszHelpFilePath;
    strHelpFile.Replace(".HLP", ".chm");
    free((void*)m_pszHelpFilePath);
    m_pszHelpFilePath = _tcsdup(strHelpFile);

Then add a help handler in CMainFrame. Put the following in CMainFrame just before END_MESSAGE_MAP and outside the AFX_MSG_MAP tags:

    ON_COMMAND(ID_HELP, CMDIFrameWnd::OnHelp)

or, if you chose for single document view:

    ON_COMMAND(ID_HELP, CFrameWnd::OnHelp)

Use ClassWizard to add an override for WinHelp. Replace the contents of WinHelp() by:

    HtmlHelp(m_hWnd, AfxGetApp()->m_pszHelpFilePath, HH_HELP_CONTEXT, nCmd == HELP_CONTEXT ? dwData : 0);

Almost ready! When you compile your project now and press F1 or choose Help Topics you'll get the warning HH_HELP_CONTEXT called without a [MAP] section. The last thing you have to do is to map, in HTML Help Workshop, topic ID's from the generated .hm file to topic files. To have the help system react on F1 in the main window you would map IDH_MAINFRAME (single document view) or IDH_HTMLDETYPE (in my demo project with multiple document view) to INDEX.HTM. To show specific help for a dialog just add a button with an ID of ID_HELP to the dialog and map the corresponding translated dialog ID to the specific topic file. In the demo project I added a button to the About box so I mapped IDH_ABOUTBOX to ABOUT.HTM.

In HTML Help these mappings are called aliases. Open the HTML Help Project with HTML Help Workshop and doubleclick on the [MAP] section. Click on Alias, Add and type the ID in the first field. Select a topic file in the second and click OK, OK.

Using bookmarks

You can force HTML Help to scroll directly to a specific spot on a help page by adding a bookmark to the HTML file. Just add a bookmark to the HTML Help file and add a # and the name of the bookmark to the alias in HTML Help Workshop. In the demo project I've added a bookmark in ABOUT.HTM. Click in the demo on Help, How to use bookmarks to view the effect.
The compiler now generates a warning that can be ignored (in this case HHC3015: Warning: An alias has been created to "Web\about.htm#Bookmark" but the file does not exist).

Distributing HTML Help

HTML Help works through a control called HHCTRL.OCX. When you want to distribute your program with HTML Help, the user should have installed the latest version. Personally I state that users of my programs should have Internet Explorer 4.01 installed before they are able to use them. Then I'm sure they have HTML Help installed (and a recent COMCTL32.DLL, also handy). On the Microsoft web you can find information about updates for HTML Help called HHUPD.EXE. It can be implemented in a silent way (hhupd /q) in your setup program so you're sure they always use the latest HTML Help control.

Known problems and updates

  • Some readers couldn't get the demo working: the message HH_HELP_CONTEXT called without a [MAP] section keeps popping up. This seems to be caused by the sequence in which the files are compiled (if the .chm file is build before the .hm file, the help file doesn't contain updated ID's). When the project is rebuild twice, the error message disappears. To ensure the .hm is build before the .chm file go to Project Settings, Settings, choose All Configurations, select the .hhp file, click on Custom build, Dependencies and add html\$(TargetName).hm.
    This article (see Creating a MFC project) as well as the demo project is updated with these changes.
  • Jayant Umrani wanted the following: (quote) HOW TO GIVE KETWORD SEARCHES DIRECTLY FRON VC++. SUPPOSE THE USER PRESSES F1 KEY WHEN HE IS SOME FEILD OF THE DAILOG BOX AND IDH IS ASSOSIATED TO SOME HTML FILE BUT THE ACTUAL TEXT IS DEEP BELOW IN THAT HTML, THEM THE HELP SHOULD ME SHOWN WITH THAT PART ON TOP (unquote). A few hours later he supplied the solution himself so I implemented it in the demo project and updated this article (see Using bookmarks). Thanks for participating!

Well, that's it! Hope you find it useful.

Downloads

Download demo project - 126 KB


Comments

  • nike heels

    Posted by Joitlerearoff on 07/07/2013 06:06am

    ksuxb planchas ghd kcpyh plancha ghd pgjsk plancha de pelo ghd jcqgp secadores ghd udxek http://planchasghd.astrologychick.org/ wqnwm karen millen dresses ngrtd karen millen outlet zhsjz karen millen sale hbcig karen millen coats grbrr http://karenmillendresses.kachile.org/ eopmr lisseur ghd ppzzg ghd lisseur ectbw ghd avis earra lisseur ghd promo ygqmg http://lisseurghd.whaboo.org/ echqs isabel marant sneakers joupo isabel marant boots alieu isabel marant sale yppfz http://isabelmarant.toonfx.org/ jrzug ash shoes mqvec ash wedge sneakers fstfg ash studded boots ucevx http://ashshoes.astrologychick.org/ asehz sac vanessa bruno ixzsu sac vanessa bruno pas cher ebivh vanessa bruno eshop acqbo http://sacvanessabruno.toonfx.org/ wasku louboutin pas cher keeuc louboutin soldes qfujr louboutin homme pas cher xjttu http://louboutinpascher.whaboo.org/

    Reply
  • chaussure nike pas cher

    Posted by Joitlerearoff on 06/19/2013 08:03am

    pviqe ugg boots bykhs ugg australia kblhy ugg boots sydney scnie ugg boots for men ajegj http://bootsaustralia.10six.org/ ilzcf louboutin pas cher kbtmn chaussures louboutin zusyl prix chaussure louboutin vaqko http://louboutinpascher.smchillel.org/ slzza jillian michaels mnyst jillian michaels 30 day shred iykjh jillian michaels dvd dssda http://fitness.kachile.org/ vsdhq insanity asylum day 4 fmoyv insanity deluxe dvd list vmthe insanity workout on sale for cheap vktgr where can you buy insanity workout videos gmzru insanity workout set for sale qqxat louis vuitton bag kksct louis vuitton handbags on sale xvqvu louis vuitton bags for cheap rpomx http://lv.smchillel.org/ qrfrr isabel marant sneakers idgcr isabel marant shoes kqqys isabel marant sneakers buy weslk http://isabelmarant.10six.org/ vkaop fitflop tnscb fitflop singapore jaemw fit flops yisqs fitflop vivo city qznrm http://fitflop.smchillel.org/

    Reply
  • cheap ghd australia

    Posted by Joitlerearoff on 06/17/2013 08:23pm

    wjwek insanity workout before and after uxjlr insanity defence nzyby insanity workout sale ebay kfyqi insanity workout for beginners xerse insanity workout dvd best price icqki sac vanessa bruno qfrmh sacs vanessa bruno hgtae sac vanessa bruno prix patoi http://sacvanessabruno.10six.org/ dexdv karen millen dresses zyudu karen miller dresses lffev karenmillen zpmpc karen millen sales vozzk http://karenmillendresses.10six.org/ tbjvs jillian michaels dykkh jillian michaels 30 day shred rpluv jillian michaels 30 day shred reviews stxvg http://fitness.kachile.org/ gkpmh fitflop jeyig fitflop singapore nmspp fitflops jfqyv fitflop fiorella hjjvj http://fitflop.smchillel.org/ vezry isabel marant sneakers yqnxz isabel marant dicker boots nzdrt isabela marant hemvn http://isabelmarant.10six.org/ uxxwk nike heels dujrq nike walking shoes dwtpw baby nike shoes uzbra http://nikeheel.smchillel.org/

    Reply
  • burberry bags

    Posted by Joitlerearoff on 06/11/2013 10:15am

    cuwjq fitflop ekeme fitflop singapore efxei fitflop sale oycqg fitflop in singapore qikpv http://fitflop.smchillel.org/ hredb burberry outlet ienxx burberry handbags mocmg burberry messenger bag vdxpm http://burberry.msvotes.org/ ruevo karen millen dresses uwtje karen miller dresses fhkod karen millen usa wxpyc cheap karen millen dresses shhuz http://karenmillendresses.10six.org/ vntei nike heels mqqeg nike shoes for men spvfn nike lebron shoes viuxa http://nikeheel.smchillel.org/ oulhj insanity workout australia buy trthd insanity fast & furious qwtbm insanity workouts dvds gkuck insanity workout how much zikqg insanity shaun t ieqka louis vuitton bag raont louis vuitton handbags outlet ujkrm authentic louis vuitton handbags outlet vxprw http://lv.smchillel.org/ hslwf ugg boots usxpi ugg australia tefqw ugg store yyyft pink ugg boots qxxlx http://bootsaustralia.10six.org/

    Reply
  • basket isabel marant

    Posted by Joitlerearoff on 06/09/2013 08:29am

    oizac hunter boots yesyv hunter rain boots nuhuj cheap hunter boots gmppg http://hunterrainboots.msvotes.org/ bnnet nike heels oyuah nike shoes on sale cliin nike shoe sale wxzkl http://nikeheel.smchillel.org/ awkoe isabel marant sneakers oitgj isabel marant wedge sneakers gmidb isabel marant s bkjca http://isabelmarant.10six.org/ ufivk pandora bracelet lxrnj pandora charm bracelets glaen authentic pandora charms txcav http://pandora.msvotes.org/ gldws longchamp bag khaxi longchamp sale gfnag longchamp le pilage gpkmn http://longchamp.msvotes.org/ hkgzj fitflop wuifs fitflop singapore osylr fitflop usa kjvpc fitflop shoes walkstar ljkrp http://fitflop.smchillel.org/ oeyce sac vanessa bruno ehauo sac vanessa bruno pas cher cwlxi vanessa bruno eshop anktl http://sacvanessabruno.10six.org/

    Reply
  • insanity shaun t

    Posted by Joitlerearoff on 05/31/2013 01:52am

    sxybv hunter rain boots yvrvy hunter rain boots sale fxrhc hunters rain boots djkwx http://hunterrainboots.welbecktiles.org/ xffpe ash shoes welni ash wedge sneakers drumg ash trash boots cvrjk http://ashshoes.area8sova.org/ fgsez fitflop krlwb fitlop osxno fitflot gmiot http://fitfloptw.astrologychick.org/ gwiag sac longchamp pliage klghb sac longchamp solde nlowo solde longchamp sozgy http://saclongchamp.area8sova.org/ wwfgw oakley sunglasses xqpbz oakley australia slcyr oakley gascan kxoey http://oakleysunglassesau.welbecktiles.org/ ltfed nike heels lhxaq nike high heels ykvli nike airs cvxdk http://nikehighheel.area8sova.org/

    Reply
  • basketball jerseys cheap,cheap reversible basketball jerseys,authentic jerseys for cheap

    Posted by mymnwoomi on 05/29/2013 11:27pm

    May perhaps 21st first early morning Beijing time period, Genuine The town authorities announced that will discipline Mourinho to be able to keep when they get home from the period. Genuine The town chief executive Florentino discussed in a press seminar inside The town the reason why spice Mourinho. " [url=http://cheapjerseyscn.weebly.com]cheap jerseys free shipping[/url] That period seriously isn't approximately the anticipation, and are unable to say that therefore negative. We hope that this upcoming discipline can certainly start a brand new period, can certainly permit the best The town onward, can certainly maintain your secure system from the team. Previous to Mourinho had not found yourself in Genuine The town intended for six consecutive decades, we all cease the winners sixteen strong, along with does not owned by the Winners Little league seeded workforce. Three years connected with Mourinho, is a interval connected with achievements, Genuine The town to their particular groups. " Florentino reported. "Last period we all played the shocking football, we all designed accurate documentation. That period, the 'certain teams' will do, yet failed to match the anticipation. My spouse and i greatly anticipation that will Mourinho can certainly discipline for countless years, however the Genuine The town devotees should understand that the demand on your pet, as well as the extremely folks that can certainly endure, an individual may endure the demand will be restrained. Regardless, Mourinho has grown an integral part of Genuine Madrid's history. " [url=http://cheapjerseyscn.weebly.com]cheap jerseys free shipping[/url] Florentino make clear the team along with Mourinho are generally negotiated surrender, they reported: "no one ended up being dismissed, this is actually the consequence connected with shared end of contract. Three years soon after, we all both equally idea it was before the close up functioning marriage in between the suitable time period. "Florentino in addition discussed the existing Genuine The town failed to tell one boss authorized the arrangement, they reported: "we have not yet who authorized the arrangement, it'll be the foreseeable future function focus right now. For a start, I'd like to cover tribute to be able to Rome Saint-Germain along with their particular overseer connected with sport activity, we all stored speaks a couple of days before, along with on Ancelotti's contract prerequisites, yet Rome St Germain shared with that people do not really want Ancelotti to be able to keep their particular. "

    Reply
  • karen millen dresses uk

    Posted by Joitlerearoff on 04/10/2013 05:09am

    vjwnn toms shoes phvkt toms shoes outlet pisbg http://casualshoesusa.blogspot.com/ nojbe toms shoes cmglp toms shoes canada ktrzl http://cheapshoescanada.blogspot.com/ hkfnb hunter boots xchny hunter rain boots sale gmvki http://hunterrainbootsale.blogspot.com/ gjjye sneakers isabelle marant ofrhz sneakers isabel marant mgovf chaussure isabelle marant uyhca http://isabelmarrantsneakers.webnode.fr/ tqqsu isabel marant shoes npxhz isabel marant dicker boots zkspz isabel marant sneaker aebgg http://isabelshoesusa.webs.com/ amyie nike high heels qjxcx nike dunk high lvfzv http://nikehighheelscheap.blogspot.com/

    Reply
  • http://www.tomsoutletw.com/ btfulo

    Posted by http://www.tomsoutletw.com/ Mandyija on 03/31/2013 04:21am

    ray ban glasses,Giggle ...... great Hello! Look at this lady's powerful! Joy a little carried away by the rapid escalation seemed carried away Betty this case also attracted the attention of people around the oakley sunglasses in the hands of flashing red and blue and yellow-green four-color light gold Longbow greet the crowd eye. Watched oakley sunglasses discount emitted arrows turned into Jinghong lightning-like disappeared in the air, and then you can hear that huge roar sounded at the same time, then as long as not a fool can guess just cause The powerful effect of the explosion from the man are mine! Curious, surprised, shocked, envy, jealousy, greed ... all the eyes are shot in small LORI who also still immersed in the joy awakened ray ban aviators,oakleysunglassesoutc.com/" title="cheap oakley sunglasses"cheap oakley sunglasses. The small assassin for a time so many different eyes note that does not have this experience this time also a little afraid, and had still the bow hand flick not help, put the arrows Shepian, but even Shepian to the is also a lot of monster died following monster is, after all, so do not have access to what targeting.

    Reply
  • womens sexy clothes

    Posted by Fishnetik1015 on 03/29/2013 09:35am

    http://spicylingeries.webs.com - Sexy LingerieHe was so pleased with the system that he had it installed in all his restaurantslingerie?has been derived from the French word http://sexylingeriecostumese.webs.com - Sexy LingerieAnd it always gives off the impression that a woman wearing this color is one who is confident, headstrong and sexy Additionally make sure you know the difference between lingerie and sexy lingerie when making your choice http://cheapspicylingerie.webs.com - Cheap Discount Lingeries boxers, and they have it Perhaps you would offer to take photos for a publication, website or edit a manuscript http://cheapspicylingerie.webs.com - cheap sexy lingerieThis isn't to say that the remaining 364 days of the year are reserved strictly for turtlenecks and sweaters or long pants and sweatshirts Carroll Baker was in the lead role http://babydollnightgowns.webs.com - Sexy BabydollsWomen love the feel of leather on their bare skin, and peeling off a tight leather teddy is a real treat!Lingerie for your baby and you can't lose! Give her a gift of lingerie, and you do yourself a favor! The gift that keeps on giving - all year round! Baby doll lingerie looks sexy and attractive and therefore has become a popular choice among customers Then be sure to role play

    Reply
  • Loading, Please Wait ...

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: October 29, 2014 @ 11:00 a.m. ET / 8:00 a.m. PT Are you interested in building a cognitive application using the power of IBM Watson? Need a platform that provides speed and ease for rapidly deploying this application? Join Chris Madison, Watson Solution Architect, as he walks through the process of building a Watson powered application on IBM Bluemix. Chris will talk about the new Watson Services just released on IBM bluemix, but more importantly he will do a step by step cognitive …

  • Live Event Date: October 23, 2014 @ 12:00 p.m. ET / 9:00 a.m. PT Despite the current "virtualize everything" mentality, there are advantages to utilizing physical hardware for certain tasks. This is especially true for backups. In many cases, it is clearly in an organization's best interest to make use of physical, purpose-built backup appliances rather than relying on virtual backup software (VBA - Virtual Backup Appliances). Join us for this eSeminar to learn why physical appliances are preferable to …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds