Paul A. O'Rear

Helpful Solutions (owner)

Sageline Software (co-owner)

pao@sageline.com

- the position item is 0 based. An integer value that specifies the position of the menu item in the menu. Position 0 is the first position in the menu.

- enabled-state. See chart below

Usage ExtInsertMenu(`parent-id', `menu-id', `menu-name', position, enabled-state)

* items in gray are not of direct use in WinHelp, but are provided for completeness.

Usage ExtAbleItem(`item-id', enabled-state)

Despite the interesting things you can do with the enabled-state parameter of ExtInsertItem and ExtInsertMenu, ExtAbleItem is only aware of the MF_ENABLED and MF_GRAYED states and will not use any of the other states.

Usage JumpHash(`filename', hash-code)

Enables jumping to a topic based on the hash value derived from the topic id

Usage PopupHash(`filename', hash-code)

Enables jumping to a topic in a popup window based on the hash value derived from the topic id

Use the Hashed value of a topic's topic ID. TopicID Hasher.

Usage Generate(windows_message/WM_XXX, wParam, lParam)

The equivalent of SendMessage() for WinHelp only - skips the requirement of an RR() routine for SendMessage.

Usage FloatingMenu()

Launches the floating menu from a hotspot or anywhere else that a macro can be executed.

Usage Command(command-number)

Uses the Resource IDs of any of the WinHelp elements as follows:

File|Open 1101

File|Print 1103

File|Exit 1105

Edit|Copy 1203

Edit|Annotate 1202

Bookmark|Define 1301

Bookmark|More 1302

(if Bookmarks are on the menu then they start with 1303 and increase from there)

Help|How to Use Help 10003

Help|Always on Top 10002

Help|About Help 1503

Items added to menus with any of the standard macros will be assigned numbers starting with 10004 in the order they are added.

Windows Help 4.0:

Uses the Resource IDs of any of the WinHelp elements as follows:

File|Open 1101

File|Print 1103

File|Exit 1105

Edit|Copy 1203

Edit|Annotate 1202

Bookmark|Define 1301

Bookmark|More 1302

(if Bookmarks are on the menu then they start with 1303 and increase from there)

Options|Keep Help on Top|Default 1470

Options|Keep Help on Top|On Top 1471

Options|Keep Help on Top|Not On Top 1472

Options|Display History Window 1453

Options|Font|Small 1462

Options|Font|Normal 1460

Options|Font|Large 1461

Options|Use System Colors 1465

Help|Version 1503

Tab() or Tab(0) -- Find

Tab(n) -- Custom Tab n

Tab(n + 1) -- Contents (if no custom tabs are defined, then Tab(1) brings

up the contents.

Notes on Tabs: From the API when Help is not yet launched, most normal methods of obtaining a specific tab fail. If you want the Contents tab use Tab(n+1), if you want the Find tab use Tab(0), if you want the Index tab, you must use the HELP_PARTIALKEY command with an empty string. Once help is launched most navigation methods work as expected; it's in the launching that it breaks down.

In WinHelp 4.0 these two macros do not work properly with the floating menu. A long standing complaint. Separators show up as blank areas, and sub-menus are not created.

Usage ShowInWindow(`window_name') or SW(`window_name')

Causes the current topic to be displayed in the window type passed in the window_name parameter.

In order to make this work correctly, the macro needs to be followed with a Generate() macro call that forces the topic to be repainted:

Generate(1030, 0, 1) - this is an undocumented native method that WinHelp itself uses to force a repaint of a topic.

ex. SW(`proc4'):Generate(1030, 0, 1)

Only the short form of this macro works?

FlushMessageQueue = Flush() = FH()

Same as Flush macro - forces WinHelp to finish processing the messages in its message queue before proceeding with the next macro.

Same as UpdateWindow() and was apparently the original name. If you check your HCW.HLP file you'll see UpdateWindow() listed with JW() as the short form... If JumpWindow() makes more sense to you, you can use it - the compiler accepts it and uses it properly.

both compile without any questions, but neither appear to work.

- when compiled and executed WinHelp specifies that this macro requires a windows 4.1 help file.

AN() for Annotate()

DEB() for DestroyWindow()

EP() for ExecProgram() which is still functional in WinHelp 4.0

TC() for TCard()

Add your own custom check marks to your help system with this interesting method:

There's a nice little feature that WinHelp has that helps in the use of API functions as macros in help files - RegisterRoutine() macro. Unfortunately, as many have found out using 16-bit DLLs with 32-bit help files can cause nightmares on Windows NT. The good news? WinHelp has some internal code that actually translates calls to a few specific OS DLLs that are used for Windows API calls, that will work whether you're on NT or not. Here's how it works:

1) first it checks if the DLL has any extension present; if not it appends ".DLL"

2) if the DLL passed is either "USER.DLL" or "USER.EXE" it converts it to "USER32.DLL"

3) if the DLL passed is either "GDI.DLL" or "GDI.EXE" it converts it to "GDI32.DLL"

4) if the DLL passed is "mmsystem.dll" it converts it to "winmm.dll"

5) on NT if it can't open the DLL it will report it missing.

6) if on 95 it will create a thunk and try to open it. If it can't do this it will report it missing.

7) it will try to get the address of the function from the DLL.

8) if it fails and the DLL passed (or modified to) is either "USER32.DLL" or "winmm.dll" it will append an "A" to the function name and try to get the address of the function again.

9) if both of these methods of obtaining the function address fail and Help Author mode is on, a message will be reported stating that

"The function xxx could not be found in xxx."

providing you with some help as to what the problem may be.

Plus: in WinHelp 4.0, the parameter list to functions passed via RR() is not case sensitive as it was in WinHelp 3.1x.

In WinHelp 3.1, RR() parameters had the following variations:

in WinHelp 4.0 and in the 32-bit operating systems all values are long/32-bits so that the parameters have the following variations:

This makes conversion of Windows API calls whose own parameter types didn't change except for the size of their data types (16-32-bits) virtually transparent and not requiring any special effort on the help author's part. It also makes it possible to use help files that use some fancy techniques only from API calls portable across all operating systems.

undocumented calls:

cf. my help files available for Internal functions, RR declarations, HELPDECO file format stuff.

typedef struct tagFSHEADER_RAM

{
FSH * fsh;
BTH * hbt;
UINT fid;
LPSTR fm;
}

where FSH is a structure of the following construction:

typedef struct tagFSH

{
WORD wMagic;
BYTE bVersion;
BYTE bFlags;
LONG lifDirectory;
LONG lifFirstFree;
LONG lifEof;
}

and BTH is a structure of the following construction:

typedef struct tagBTH

{
WORD wMagic;
BYTE bVersion;
BYTE bFlags;
WORD cbBlock;
CHAR rgchFormat[15];
short bkFirst;
short bkLast;
short bkRoot;
short bkFree;
short bkEOF;
short cLevels;
DWORD lcEntries;
}

WinHelp 3.1/3.50.900 (32-bit version) - including BTree and Internal File System test dialogs, add-button, execute macro, etc.

WinHelp 4.0 - including special error and processing messages as well as extra floating menu options.