WinHelp virus programmers reference ÜÛÛÛÛÛÜ ÜÛÛÛÛÛÜ ÜÛÛÛÛÛÜ Compiled by ÛÛÛ ÛÛÛ ÛÛÛ ÛÛÛ ÛÛÛ ÛÛÛ Darkman/29A ÜÜÜÛÛß ßÛÛÛÛÛÛ ÛÛÛÛÛÛÛ ÛÛÛÜÜÜÜ ÜÜÜÜÛÛÛ ÛÛÛ ÛÛÛ ÛÛÛÛÛÛÛ ÛÛÛÛÛÛß ÛÛÛ ÛÛÛ ÄÄÄÄÄÄÄÄÄÄÄÄ Introduction ÄÄÄÄÄÄÄÄÄÄÄÄ None of the information in this article is written by me, I found the information included in this article usefull while I was researching HLP infection. I would like to thank Olson Software for the WinHelp macros, Don Lammers from Shadow Mountain Tech for the WinHelp API function and the WinHelp command line and Prizzy/29A for providing me with a list of WinHelp v 4.0 macros. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ WinHelp macros ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ About Displays the WinHelp About dialog box. Usage About() Alias None Description The About macro displays the WinHelp About dialog box. Parameters None Windows MainSecondary Comments You can add your own text to the About dialog box by entering some text in the Copyright box in the Options tab of the Project|Settings dialog. Example This example displays the WinHelp About dialog box: About() AddAccelerator Assigns a macro to a key combination Usage AddAccelerator(key, shift-state, `macro'') Alias AA Description The AddAccelerator macro associates a key or key combination with a help macro. When the chosen keys are pressed the macro is executed. Parameters key Specifies the key code. (Note you need to add a 0x in front of the hexadecimal value for WinHelp to recognize the key correctly.). shift-state Specifies the combination of Shift, Ctrl, and Alt keys to be used in combination with key. This parameter may be one of the following values Value Modifier keys 0 None 1 Shift 2 Ctrl 3 Shift+Ctrl 4 Alt 5 Alt+Shift 6 Alt+Ctrl 7 Shift+Alt+Ctrl macro Specifies the macro to be executed when the accelerator key(s) are pressed. This parameter must be enclosed within quotation marks. Multiple macros can be executed by separating each macro with a semicolon. Windows MainSecondary Comments This macro allows you to provide "shortcut" keys, so that macros can be executed more quickly.Check the documentation for the macro you that will be executed when the keystrokes are entered if the accelerator will be executed in a secondary window, as some macros don't operate in secondary windows. Once added, an accelerator can be removed through the RemoveAccelerator macro. Example This macro displays the virtual key codes topic in the codes secondary window when CTRL+V is pressed anytime after this macro has been executed: AddAccelerator(0x56,2,"JumpId(`macros.hlp>codes', `Virtual_Key_Codes')") See Also RemoveAccelerator ALink (only in WinHelp v 4.0) Searches for A-keywords. Usage ALink(`keyword[; keyword'] [, type[, `context-string' [, `window-name']]]) Alias AL Description The ALink macro searches for A-keywords with the specified keyword within the current help file(s). Parameters keyword Specifies one or more keywords to search for. Multiple keywords must be separated by a semicolon. If any keyword contains a comma, the entire keyword string must be enclosed in quotation marks. type Specifies the action to perform if one or more keywords are found. If this parameter is not specified or is zero, the default action is always to display the Topics Found dialog box containing the topic title. This parameter may specify one or more of the following values, added together. Value Meaning 1 Specifies that if only one topic matches any of the keywords, WinHelp should jump directly to that topic. 2 Specifies that if a keyword is found in more than one Help file, WinHelp should display the title of the Help file (as specified in the contents [.cnt] file) beside the topic title in the Topics Found dialog box. 4 Specifies that the macro should return a value indicating whether or not there is at least one match. The TestALink macro is converted by Help Workshop into an ALink macro with this parameter. context-string A string that identifies the context string of the topic to display in a pop-up window if no matches are found. If this parameter is not specified, WinHelp displays a message box with the text "No additional information is available". To specify a topic in a different Help file, the topic ID should end with an ‘@’ character and the name of the Help file. window-name Specifies the window name in which to display the topic. The window name is the name you have assigned to the window in the Windows tab of the Project|Settings dialog. For the main window, this parameter should be "main". If this parameter is not specified, the window type that is specified for a topic (if one is defined) is used, or the default or current window is used. If this macro results in an interfile jump, the window type must be defined in the project for the Help file that is being jumped to. Windows MainSecondary Comments The ALink macro searches for A-keyword matches in the current Help file. If the Help file is associated with a contents file, WinHelp searches all Help files specified in the contents file for matching A-keywords.The ALink macro is identical to the KLink macro except that it searches for A-keywords instead of K-keywords. Example This example displays a list of topics that contain contain the "network printing" or "local printing" keywords in A-footnotes: ALink(network printing;local printing) See Also KLink TestALink Annotate Displays the WinHelp dialog box for entering annotations Usage Annotate() Alias None Description The Annotate macro displays the WinHelp annotation dialog. Parameters None Windows MainSecondary Comments When executed from within a popup, the annotation created is associated with the topic that the popup was called from.It is not recommended that you call this macro within a popup under WinHelp 4.0. Example This macro displays the WinHelp annotation dialog: Annotate() AppendItem Appends a menu item to the end of an existing menu Usage AppendItem(`menu-id', `item-id', `item-name', `macro'') Alias AI (only under WinHelp 4.0) Description The AppendItem macro appends a menu item to the end of an existing menu. The existing menu can be either a standard menu or one created with InsertMenu or ExtInsertMenu Parameters menu-id Specifies the name of the menu the new item will be inserted into. The menu name can be the name assigned when created with the InsertMenu or ExtInsertMenu macros, or one of the following standard menus: Name Menu mnu_file File mnu_edit Edit mnu_bookmark Bookmark mnu_help Help mnu_main Append the item to the end of the menu bar. mnu_floating The floating menu item-id Specifies the name that WinHelp uses internally to identify the menu item. This name can be used as the item-id in the CheckItem, DeleteItem, DisableItem, EnableItem, ExtAbleItem or UncheckItem macros. item-name Specifies the name to be displayed on the menu for this item. Within the quotation marks, place an ampersand (&) before the character to be used as the item's accelerator key. macro Specifies the macro to be executed when the menu item is selected. The macro must be in single quotation marks, with multiple macros in a string separated by semicolons. Windows Main Comments If the accelerator key you assign to the new menu item is conflicts with another menu access key, WinHelp will display an "Unable to add item" error message, and the item will not be added to the menu.You can append up to 20 items to WinHelp's context menu (mnu_floating) Example This macro appends a menu item labled Notepad to the File menu. Choosing this menu item will execute the Notepad accessory. AppendItem(`mnu_file', `itm_notepad', `&Notepad', `ExecProgram(`notepad.exe', 0)') See Also ChangeItemBinding CheckItem DeleteItem DisableItem EnableItem ExtAbleItem ExtInsertItem InsertItem ResetMenu Back Displays the previous topic in the back list Usage Back() Alias None Description The Back macro displays the previous topic in the back list. The back list is a list of all topics accessed since starting the current instance of WinHelp. Calling macro is the same as choosing the [Back] button on the button bar. Parameters None Windows MainSecondary (only in WinHelp v 4.0) Comments If the back list contains no topics, this macro has no effect. Under WinHelp 4.0 the macro works only for topics that were displayed in the current window type; it does not display topics that were displayed in other window types. Example This macro displays the previous topic in the back list: Back() See Also BackFlush History BackFlush (only in WinHelp v 4.0) Removes the back history list from the current window Usage BackFlush() Alias BF Description The BackFlush macro removes the back history list from the current window. Parameters None Windows MainSecondary Comments This macro does not affect the history list displayed in the History window. Example This example clears all items from the back list: BackFlush() See Also Back Flush BookmarkDefine Displays the Define dialog box from the Bookmark menu. Usage BookmarkDefine() Alias None Description The BookmarkDefine macro displays the Bookmark Define dialog. Calling this macro is the same as using the Bookmark|Define menu command. Parameters None Windows MainSecondary Comments When executed from a popup topic, bookmarks created are associated with the topic that displayed the popup window. Bookmarks do not keep track of the window type the topic was originally displayed in. When you use the Bookmark menu or call the BookmarkMore macro, the bookmark topic is displayed in the current window type. Example This macro displays the Bookmark Define dialog box: BookmarkDefine() See Also BookmarkMore BookmarkMore Displays the More dialog box from the Bookmark menu Usage BookmarkMore() Alias None Description The BookmarkMore macro displays the More dialog from the Bookmark menu. The more command is displayed on the Bookmark menu only if more than nine bookmarks are defined. Parameters None Windows MainSecondary Comments Selecting a bookmark from the Bookmark dialog will display the topic to which the bookmark is attached in the currently active window. Using this macro is the only way to select a bookmark from a secondary window. Example This macro displays the Bookmark More dialog box: BookmarkMore() See Also BookmarkDefine BrowseButtons Adds browse buttons to the button bar Usage BrowseButtons() Alias None Description The BrowseButtons macro adds browse buttons ([<<] and [>>]) to the button bar. Parameters None Windows MainSecondary (only in WinHelp v 4.0) Comments The order of which buttons on the button bar is determined by where the b macro is executed in relation to other button creation and removal macros in the Macros tab of the Project|Settings dialog. Once added to the button bar, browse buttons can not be removed.Note: You do not need to use this macro to add browse buttons to your windows - you can use the Button Bar dialog available from the Windows tab of the Project|Settings dialog. Example This macro displays the browse buttons on the button bar: BrowseButtons() See Also CreateButton Next Prev ChangeButtonBinding Changes the macro assigned to a help button Usage ChangeButtonBinding(`button-id', `macro') Alias CBB Description The ChangeButtonBinding macro assigns a new macro to an existing help button, replacing the button's previously defined macro. Parameters button-id A string that specifies the name assigned to the button when created using the CreateButton macro, or one of the following standard buttons. Id Button btn_contents [Contents] btn_search [Search] btn_back [Back] btn_history [History] btn_previous [<<] btn_next [>>] macro Specifies the macro that is executed when the button is chosen. Multiple macros should be separated by semicolons. Windows Main Comments Using this macro to change the standard buttons doesn't change the operation of the macro that the button uses. For example if you change the macro associated with the Search button, using the Search macro will still display the search dialog. Example This macro changes the button previously created with the identifier of `btn_notepad' to display the Annotate dialog. ChangeButtonBinding(`btn_notepad', `Annotate()') See Also ChangeEnable CreateButton DestroyButton DisableButton EnableButton Next Prev ChangeEnable (only in WinHelp v 4.0) Assigns a macro to a button bar button and enables that button. Usage ChangeEnable(`button-id', `macro') Alias CE Description The ChangeButtonBinding macro assigns a new macro to an existing help button, replacing the button's previously defined macro and then enables that button. Parameters button-id A string that specifies the name assigned to the button when created using the CreateButton macro, or one of the following standard buttons. Id Button btn_contents [Contents] btn_search [Search] btn_back [Back] btn_history [History] btn_previous [<<] btn_next [>>] macro Specifies the macro that is executed when the button is chosen. Multiple macros should be separated by semicolons. Windows MainSecondary Comments This macro is equivalent to calling both ChangeButtonBinding and EnableButton. Example This example changes the macro for the Back button and enables the button: ChangeEnable(`btn_back', `About()') See Also ChangeButtonBinding CreateButton DestroyButton DisableButton EnableButton Next Prev ChangeItemBinding Changes the macro assigned to a menu item Usage ChangeItemBinding(`item-id', `macro') Alias CIB Description The ChangeItemBinding macro assigns a new macro to a menu item, replacing the items previously defined macro Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macros, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top macro Specifies the macro that is execute when the item is selected. Multiple macros should be separated by semicolons. Windows Main Comments Using this macro to change the standard menu items doesn't change the operation of the macro that the item uses. For example if you change the macro associated with the Help|How to Use Help item, using the HelpOn macro will still display the how to use help file. Example This macro changes the menu item previously created with the identifier of `itm_paintbrush' to display the WinHelp about box: ChangeItemBinding(`itm_paintbrush', `About()') See Also AppendItem CheckItem DeleteItem DisableItem EnableItem ExtAbleItem ExtInsertItem InsertItem ResetMenu UncheckItem CheckItem Places a check mark beside a menu item Usage CheckItem(`menu-id') Alias CI Description The CheckItem macro places a check mark () beside a menu item. Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macro, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top Windows Main Comments Check marks can be removed by the UncheckItem macro. Example This macro places a check mark beside the menu item previously created with the identifier of `itm_paintbrush'. CheckItem(`itm_paintbrush') See Also AppendItem ChangeItemBinding DeleteItem DisableItem EnableItem ExtAbleItem ExtInsertItem InsertItem ResetMenu UncheckItem CloseSecondarys (only in WinHelp v 4.0) Closes all but the current secondary window Usage CloseSecondarys() Alias None Description The CloseSecondarys macro closes all but the current secondary window. Parameters None Windows MainSecondary Example This example closes all but the current window: CloseSecondarys() See Also CloseWindow Exit FocusWindow PositionWindow CloseWindow Closes a help window Usage CloseWindow(`window-name') Alias None Description The CloseWindow macro closes a specific WinHelp window. Parameters window-nameThe name of the window to close. This is the name you have assigned to the window in the Windows tab of the Project|Settings dialog. The main window can be closed by setting this parameter to `main'. Windows MainSecondary Comments If the window doesn't exist WinHelp ignores this macro. Under WinHelp 4.0 if the main window is closed, and no other windows are open, WinHelp will quit. Example This macro will close the main WinHelp window: CloseWindow(`main') See Also CloseSecondarys Exit FocusWindow PositionWindow Command (undocumented) Executes a WinHelp menu command Usage Command(command-number) Alias None Description The Command macro executes the WinHelp menu command of the number passed to it. Parameters command-number A number in the range 0 to 65,535 that specifies the menu command to be executed. The standard menu item numbers are: Menu Item Number File|Open 1101 File|Print Topic 1103 File|Print Setup 1104 File|Exit 1105 Edit|Copy 1203 Edit|Annotate 1202 Bookmark|Define 1301 Bookmark|More 1302 Defined Bookmarks 1303, 1304 etc... Help|How to Use Help 10003 Help|Always on Top 10002 Help|About 1503 Windows MainSecondary Comments Items added to menus are given number starting with 10004, in the order in which they are added. Example This macro displays WinHelp's Edit|Annotate window: Command(1202) See Also About Annotate BookmarkDefine BookmarkMore CopyDialog Exit FileOpen Generate HelpOn HelpOnTop Print PrinterSetup Compare (only in WinHelp v 4.0) Compares two Windows Help files. Usage Compare(`help-filename') Alias None Description The Compare macro displays a Help file in a second instance of WinHelp. The current Help file and the second Help file are displayed side-by-side Parameters help-filename Specifies the name of the help file to display Windows MainSecondary Comments Most actions performed in one Help file (for example, clicking jumps or the Back and browse buttons) will be automatically reflected in the other file.This macro is useful for comparing original and translated versions of the same Help file. You can run this macro from the Jump dialog box (which can be accessed by pressing CTRL+SHIFT+J while in WinHelp) by typing the following in the Enter Topic Identifier text box: !compare("filename.hlp") For filename.hlp, substitute the name of the file that you want to compare to the one that is already open. Example This example compares this help file with the HWA help file: Compare(`hwawin.hlp') See Also Test Contents Displays the contents topic of the current help file Usage Contents() Alias None Description The Contents macro displays the contents topic of the current help file in the main window. Executing this macro is the same as selecting the [Contents] button on the WinHelp button bar. Under WinHelp 4.0 this macro displays the Contents tab in the Help Topics dialog box if the Help file is associated with a contents file that specifies Contents tab information. If the Help file is not associated with a contents file, the Contents macro displays the default (contents) topic in the current Help file. Parameters None Windows Main Comments The contents topic can be set through the Options tab of the Project|Settings dialog.The options for creating .CNT files can be set through the CNT tab of the Project|Settings dialog. Example This macro displays the contents topic of this help file: Contents() See Also Finder JumpContents SetContents ControlPanel (only in WinHelp v 4.0) Opens a control panel applet with a specific tab on top. Usage ControlPanel(`cpl-name'[, `panel-name', tabnum]) Alias None Description The Control Panel macro opens a control panel applet with a specific tab on top. Parameters cpl-name Specifies the name of the program that contains the control panel applet. panel-name Specifies the name of the control panel applet. This must be identical to the text that appears under the control panel applet's icon. tabnum Specifies the number of the tab to display on top. The first tab is number 0, the second tab is number 1, and so on. Windows MainSecondary Comments Not all control panel applets recognize the panel_name and tabnum parameters. Example This example displays the background tab of the Display control panel applet: ControlPanel("desk.cpl","Display",0) See Also ExecFile CopyDialog Displays the Copy dialog box. Usage CopyDialog() Alias None Description The CopyDialog macro displays the Copy dialog box. The text of the current topic is displayed in the Copy dialog box so that you may select which parts to copy to the clipboard. Executing this macro is the same as selecting the Edit|Copy menu command. Parameters None Windows MainSecondary Comments If this macro is executed from a popup, the text of the topic that displayed the popup will be placed in the Copy dialog. Under WinHelp 4.0, this macro is obsolete. In version 3.x of WinHelp, this macro displayed a dialog box. WinHelp 4.0 simply copies the entire topic to the Clipboard. New Help files should use the CopyTopic macro instead. Example This macro displays the text of this topic in the Copy dialog: CopyDialog() See Also CopyTopic CopyTopic Copies the text of the currently displayed topic to the clipboard. Usage CopyTopic() Alias CT (only in WinHelp v 4.0) Description The CopyTopic macro copies all text in the current topic to the Clipboard. Executing this macro is the same as pressing CTRL+INSERT in the help window. Parameters None Windows MainSecondary Comments If this macro is executed from a popup, the text of the topic that displayed the popup will be placed on the clipboard.This macro only copies text to the clipboard. Graphics are not copied to the clipboard. Example This macro copies all text in the current topic to the clipboard: CopyTopic() See Also CopyDialog CreateButton Adds a new button to the button bar Usage CreateButton(`button-id, `name', `macro') Alias CB Description The CreateButton macro adds a new button to the end of the WinHelp button bar. Parameters button-id The name that WinHelp will use internally to identify this button. This name can be used in the ChangeButtonBinding, DestroyButton, DisableButton and EnableButton macros. name A string of up to 29 (96 under WinHelp 4.0) characters that specifies the text that will be displayed on the button. Any character coming after an ampersand (&) will be used as the button's accelerator. To display an ampersand put && in the string. macro Specifies the macro that is executed when the button is chosen. Multiple macros should be separated by semicolons. Windows Main Comments Since WinHelp uses 4 of the 22 slots for custom buttons there are only 18 slots available for custom buttons. Note that that BrowseButtons macro uses two slots.The placement of buttons on the button bar is controlled by the order in which the CreateButton and BrowseButtons macros are executed. Under WinHelp 4.0, if no accelerator is specified, WinHelp automatically chooses the first letter that can be used as an accelerator without conflicting with any previous buttons on the button bar. If an accelerator is specified and it conflicts with a previous button (including standard WinHelp buttons), WinHelp attempts to move the accelerator to the first letter that does not conflict. If no such letter can be found, the accelerator will not be changed. If users attempt to use the accelerator in this case, WinHelp displays a dialog box asking them to choose which button they want. Example This macro creates a button that will display the Notepad application. CreateButton("btn_notepad","&Notepad"," ExecProgram(`Notepad.exe',0)") See Also BrowseButtons ChangeButtonBinding ChangeEnable DestroyButton DisableButton EnableButton DeleteItem Removes an item from a menu. Usage DeleteItem(`item-id') Alias None Description The DeleteItem macro removes an item from a WinHelp menu. Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macro, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top Windows Main Comments The ResetMenu macro can be used to restore all standard menu items. Example This macro removes the menu item previously created with the identifier of `itm_paintbrush'. DeleteItem(`itm_paintbrush') See Also AppendItem ChangeItemBinding CheckItem DisableItem EnableItem ExtAbleItem ExtInsertItem InsertItem UncheckItem DeleteMark Removes a marker. Usage DeleteMark(`marker-name') Alias None Description The DeleteMark macro remove a marker previously added by the SaveMark macro. Parameters marker-name A string that specifies the mark to be deleted. Windows MainSecondary Comments If the mark does not exist WinHelp will display a "Help topic does not exist" error message. Therefore it is recommended that DeleteMark is used in an IfThen or IfThenElse macro as shown in the example for this macro. Example This macro deletes the `Clock' mark if it exists: IfThen(IsMark(`Clock'),"DeleteMark(`Clock')") See Also GotoMark IfThen IfThenElse IsMark IsNotMark Not SaveMark DestroyButton Removes a button from the button bar. Usage DestroyButton(`button-id') Alias None Description The DestroyButton macro removes a button added using the CreateButton macro. Parameters button-id A string that specifies the name assigned to the button when created using the CreateButton macro. Windows Main Comments The standard WinHelp buttons can not be removed using this macro. Example This macro removes a button previously created with the identifier of `btn_notepad', from the button bar: DestroyButton(`btn_notepad') See Also BrowseButtons ChangeButtonBinding ChangeEnable CreateButton DisableButton EnableButton DisableButton Disables a button on the button bar. Usage DisableButton(`button-id') Alias DB Description The DisableButton macro disables (grays) a button on the WinHelp button bar. The button will not be available until re-enabled with the EnableButton macro. Parameters button-id A string that specifies the name assigned to the button when created using the CreateButton macro, or one of the following standard buttons. Id Button btn_contents [Contents] btn_search [Search] btn_back [Back] btn_history [History] btn_previous [<<] btn_next [>>] Windows Main Comments Although this macro can be used to disable a standard button, WinHelp may re-enable depending on the users action. For example, each time a new topic is displayed the History and back buttons are re-enabled. The history button is re-enabled every time the history list is updated. The contents and search buttons remain disabled until the EnableButton macro is called to enable the button or an interfile link is selected. The BrowseButtons macro re-enables all standard buttons so if you disable a standard button it should be done after the BrowseButtons macro has executed. Example This macro disables the button previously created with the identifier of `btn_notepad': DisableButton(`btn_notepad') See Also BrowseButtons ChangeButtonBinding ChangeEnable CreateButton DestroyButton EnableButton DisableItem Disables a menu item. Usage DisableItem(`item-id') Alias DI Description The DisableItem macro disables (grays) a WinHelp menu item. The item will remain disabled until re-enabled with the EnableItem or ExtAbleItem macros, or until the menu is reset using the ResetMenu macro. Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macro, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top Windows Main Comments The ResetMenu macro can be used to restore all standard menu items. Example This macro disables the menu item previously created with the identifier of `itm_paintbrush': DisableItem(`itm_paintbrush') See Also AppendItem ChangeItemBinding CheckItem DeleteItem EnableItem ExtAbleItem ExtInsertItem InsertItem UncheckItem EnableButton Enables a button on the button bar. Usage EnableButton(`button-id') Alias EB Description The EnableButton macro enables a button that was previously disabled through the DisableButton macro. Parameters button-id A string that specifies the name assigned to the button when created using the CreateButton macro, or one of the following standard buttons. Id Button btn_contents [Contents] btn_search [Search] btn_back [Back] btn_history [History] btn_previous [<<] btn_next [>>] Windows Main Comments Although this macro can be used to enable a standard button, doing so may cause unexpected results. For example, enabling the search button in a file where there are no keywords is not recommended.Under WinHelp 4.0 to enable a button and change its macro binding at the same time, use the ChangeEnable macro. Example This macro enables the button previously created with the identifier of `btn_notepad': EnableButton(`btn_notepad') See Also BrowseButtons ChangeButtonBinding ChangeEnable CreateButton DestroyButton DisableButton EnableItem Enables a menu item. Usage EnableItem(`item-id') Alias EI Description The EnableItem macro re-enables a menu item previously disabled through the DisableItem or ExtAbleItem macros. Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macro, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top Windows Main Comments None Example This macro enables the menu item with the identifier of `itm_paintbrush': EnableItem(`itm_paintbrush') See Also AppendItem ChangeItemBinding CheckItem DeleteItem DisableItem ExtAbleItem ExtInsertItem InsertItem ResetMenu UncheckItem EndMPrint (only in WinHelp v 4.0) Terminates printing of multiple topics. Usage EndMPrint() Alias None Description The EndMPrint dismisses the printing message box and terminates the printing of multiple topics. Parameters None Windows MainSecondary Comments To start printing multiple topics use the InitMPrint macro. Example This example terminates printing of multiple topics: EndMPrint() See Also InitMPrint MPrintHash MPrintId ExecFile (only in WinHelp v 4.0) Executes a program. Usage ExecFile(`program'[, `arguments'[, display-state[, `context-string']]]) Alias EF Description The ExecFile macro executes a program or the program associated with a file. Parameters program Specifies the name of the program to be run or the name of a file. If a file is specified, the program associated with that file type is started. arguments Specifies the command-line arguments to send to the program. display-state Specifies a value indicating how the program's window is to be shown. If this parameter is not specified, SW_SHOW is used (activates the window and shows it in its default size and position). This optional parameter can be one of the following values: Value Meaning SW_HIDE Hides the window. SW_MINIMIZE Minimizes the window. SW_RESTORE Restores the window to its original size and position if the window is minimized or maximized. SW_SHOW Activates the window and displays it in its current size and position. SW_SHOWMAXIMIZED Activates the window and maximizes it. SW_SHOWMINIMIZED Activates the window and displays it minimized. SW_SHOWMINNOACTIVE Displays the window minimized, but WinHelp keeps the focus. SW_SHOWNA Displays a window in its current state, but WinHelp keeps the focus. (If the window was minimized before this call, it will stay minimized.) SW_SHOWNOACTIVATE Displays a window in its most recent size and position, but WinHelp keeps the focus. SW_SHOWNORMAL Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_RESTORE) context-string A string that identifies the context string of the desired topic. Windows MainSecondary Comments If a path is specified, WinHelp first searches for the file in the specified path. If the file is not found or no path was specified, WinHelp uses the standard search algorithm. Example This example opens the WIN.INI file in the program associated with .ini files: ExecFile(win.ini) See Also ShellExecute ExecProgram Executes an application. Usage ExecProgram(`command-line', display-state) Alias EP Description The ExecProgram macro executes an application. Parameters command-line A string that specifies the command line for the application to be executed. display-state An integer value that specifies how the application is to be displayed after execution. The value may be one of the following: Value Meaning 0 Normal display 1 Minimized 2 Maximized Windows MainSecondary Comments The ExecProgram macro uses the current working directory to execute the application from. So, if the working directory needs to be different in order for the application to work you will need to write a custom macro or change the application. Some applications ignore the display-state parameter, while in other applications it can cause unpredictable results. It is recommended that the display-state parameter always be set at 0. This macro is obsolete under WinHelp 4.0. Use the ExecFile macro instead. Example This macro executes the Windows Clock application: ExecProgram(`clock.exe', 0) Exit Exits the WinHelp application. Usage Exit() Alias None Description The Exit macro exits the WinHelp application. Executing this macro is the same as choosing the File|Exit menu command. Parameters None Windows MainSecondary Comments Executing this macro closes all open help windows (main and secondary). Example This macro exits the current WinHelp session: Exit() ExtAbleItem (undocumented) Enables or disables a menu item Usage ExtAbleItem(`item-id', enabled-state) Alias None Description The ExtAbleItem macro enables or disables a menu item. Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macro, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top enabled-state An integer value that specifies whether the item is to be enabled or disabled. The value may be one of the following: Value Meaning 0 Enable item 1 Disable item Windows Main Comments Any even value for the enabled-state parameter will enable the item, while any odd number will disable the item. However, it is recommended that only the above two values be passed. Example This macro disables the menu item previously created with the identifier of `itm_paintbrush': ExtAbleItem(`itm_paintbrush', 1) See Also AppendItem ChangeItemBinding CheckItem DeleteItem DisableItem EnableItem ExtInsertItem InsertItem ResetMenu UncheckItem ExtInsertItem (undocumented) Insert an item in a WinHelp menu. Usage ExtInsertItem(`menu-id', `item-id', `item-name', `macro', position, display-state) Alias None Description The ExtInsertItem macro inserts an item into a WinHelp menu and allows the initial enabled state to be specified. Parameters menu-id A string that specifies the name assigned to the menu when it was created with the ExtInsertMenu or InsertMenu macros. The menu-id can also be one of the following standard menus: Id Menu Name mnu_file File mnu_edit Edit mnu_bookmark Bookmark mnu_help Help mnu_main The menu bar mnu_floating The floating menu item-id The name that WinHelp will use internally to identify this menu item. This id can be used in the CheckItem, DeleteItem, DisableItem, EnableItem, ExtAbleItem and UncheckItem macros to manipulate the item. name A string that specifies the text that will be displayed in the menu for this item. Any character coming after an ampersand (&) will be used as the item's accelerator. To display an ampersand put && in the string. macro Specifies the macro that is executed when the button is chosen. Multiple macros should be separated by semicolons. position Specifies the numeric position of the menu item in the menu. Position 0 is the first position in the menu. display-state Specifies the state of the menu item. This parameter may be one of the following values: Value Meaning 0 Enables the menu item 1 Disables the menu item (and grays it). 2 Disables the menu item (but does not gray it). 8 Displays a check mark beside the menu item. 32 Places the the item in a new column with a vertical line between the column. 64 Places the the item in a new column with no dividing line between the column. 2048 Add a separator bar to the menu. Windows Main Comments When assigning an accelerator key for a menu item you must ensure that it is unique within the menu. If you assign a key that conflicts with another accelerator key, WinHelp will display an "Unable to add item" error message and the item will not be added to the menu.Using values for the display-state parameter other than those listed above may cause unpredictable results. Example This macro adds a separator below the first item in the Help menu: ExtInsertItem("mnu_help","itm_hsep","","",1,2048) See Also AppendItem ChangeItemBinding CheckItem DeleteItem DisableItem EnableItem ExtAbleItem InsertItem ResetMenu UncheckItem ExtInsertMenu (undocumented) Inserts a sub menu as an item in a previously defined menu. Usage ExtInsertMenu(`parent-id', `menu-id', `menu-name', position, enabled-state) Alias None Description The ExtInsertMenu macro inserts a sub menu as an item in a previously defined menu and allows the initial enabled state to be specified. Parameters parent-id A string that specifies the name assigned to the menu in which the new menu is to be inserted. For a user-defined menu, this is the name assigned to the menu when it was created with the ExtInsertMenu or InsertMenu macros. The menu-id can also be one of the following standard menus: Id Menu Name mnu_file File mnu_edit Edit mnu_bookmark Bookmark mnu_help Help mnu_main The menu bar mnu_floating The floating menu menu-id The name that WinHelp will use internally to identify this menu. This id can be used in the AppendItem, ExtInsertItem and ExtInsertMenu macros to manipulate the item. name A string that specifies the menu name. Any character coming after an ampersand (&) will be used as the item's accelerator. To display an ampersand put && in the string. position Specifies the numeric position of the menu item in the menu. Position 0 is the first position in the menu. enabled-state Specifies the state of the menu. This parameter may be one of the following values: Value Meaning 0 Enables the menu item and doe 1 Disables the menu item (and grays it). Windows Main Comments When assigning an accelerator key for a menu item you must ensure that it is unique within the menu. If you assign a key that conflicts with another accelerator key, WinHelp will display an "Unable to add item" error message and the item will not be added to the menu.Note that while it is possible to create an initially disabled menu - there is no macro that re-enable a disabled macro. Using values for the display-state parameter other than those listed above may cause unpredictable results. Example This macro adds an information menu below the first item in the Help menu: ExtInsertMenu("mnu_help","mnu_info","Information",1, 0) See Also InsertMenu ResetMenu FileExist (only in WinHelp v 4.0) Checks to see whether a file exists. Usage FileExists(`filename') Alias FE Description The FileExists macro checks to see whether the specified file or program exists.. Parameters filename Specifies the name of the file. Windows MainSecondary Comments This macro can be used in conjunction with macros such as IfThenElse, which use the result of a Boolean macro to determine what action to take.If a path is specified, WinHelp first searches for the file in the specified path. If the file is not found or no path was specified, WinHelp uses the standard search algorithm. Example This example checks to see if "Myapp.exe" has been installed. If the file is present, WinHelp runs it. If the file is not present, WinHelp displays a topic: IfThenElse(FileExist(myapp.exe), ExecFile(myapp), JumpId(install_my_app)) FileOpen Displays the WinHelp File Open dialog box. Usage FileOpen() Alias FO (only in WinHelp v 4.0) Description The FileOpen macro displays the File Open dialog box and allows the user to select a new help file to be displayed. This macro is the same as selecting the File|Open menu command. Parameters None Windows MainSecondary Comments If this macro is executed from within a secondary window the contents topic will be displayed in the secondary window, leaving the user without buttons and menus. Not all help authors will force topics to be displayed in the main window. Example This macro displays the WinHelp File Open dialog: FileOpen() Find (only in WinHelp v 4.0) Displays the Find tab Usage Find() Alias None Description The Find macro displays the Find tab in the Help Topics dialog box. Parameters None Windows MainSecondary Example This example displays the Find tab: Find() Finder (only in WinHelp v 4.0) Displays the Help Topics dialog box. Usage Finder() Alias FD Description The Finder macro displays the Help Topics dialog box. Parameters None Windows MainSecondary Example This example displays the Help Topics dialog box: Finder() FloatingMenu (undocumented) Displays the WinHelp floating menu. Usage FloatingMenu() Alias None Description The FloatingMenu macro displays the WinHelp loading menu at the current mouse cursor position. Parameters None Windows Main Comments The items you want displayed in the floating menu must have been added prior to the execution of this macro. If the floating menu has no items no menu is displayed.The floating menu (if it includes any items) is always accessible through pressing the Right mouse button while in the main WinHelp window.You can add as many as 20 menu items to the floating menu. Example This macro adds an item to the floating menu and then displays the floating menu: AppendItem("mnu_floating","flt_about","About","About()"); FloatingMenu() See Also ResetMenu Flush (only in WinHelp v 4.0) Flushes any pending message. Usage Flush() Alias FH Description The Flush macro causes WinHelp to process any pending messages, including previously called macros. Parameters None Windows MainSecondary Example This example flushes all pending messages: Flush() See Also BackFlush FocusWindow Changes the focus to the specified WinHelp window. Usage FocusWindow(`window-name') Alias None Description The FocusWindow macro changes the focus to the specified window - either the main help window or any secondary window. Parameters window-name Specifies the window name you have assigned to the window in the Windows tab of the Project|Settings dialog. For the main window, this parameter should be "main". Windows MainSecondary Comments If the specified window does not exist, WinHelp ignores this macro. Example This macro changes the focus to the main WinHelp window: FocusWindow(`main') See Also CloseSecondarys CloseWindow PositionWindow Generate (undocumented) Posts a message to the WinHelp window. Usage Generate(wMsg, wParam, lParam) Alias None Description The Generate macro posts a message to the WinHelp window. Parameters wMsg An integer that indicates the windows message to post. wParam Although WinHelp expects a long integer in this parameter, sending an unsigned integer makes more sense and is the same as used for the API call WinHelp uses. lParam The lParam expected for this message. Windows MainSecondary Comments None Example This macro executes the File|Print menu command: Generate(273,1103,0) See Also Command GotoMark Jumps to a text marker. Usage GotoMark(`marker-text') Alias None Description The GotoMark macro jumps to a text marker that was previously set with the SaveMark macro. Parameters marker-text A string that specifies the mark to go to. Windows MainSecondary Comments If the mark does not exist WinHelp will display a "Help topic does not exist" error message. Therefore it is recommended that GotoMark is used in an IfThen or IfThenElse macro as shown in the example for this macro. Example This macro jumps to the `Clock' mark if it exists: IfThen(IsMark(`Clock'),"GotoMark(`Clock')") See Also DeleteMark IfThen IfThenElse IsMark IsNotMark Not SaveMark HelpOn Display the current "Help on Help" file. Usage HelpOn() Alias None Description The HelpOn macro displays the help file for the WinHelp application. Calling this macro is the same as selecting the Help|How to Use Help menu command. Parameters None Windows MainSecondary Comments The default "Help on Help" file is WINHELP.EXE.You can change the current "Help on Help" file through the SetHelpOnFile macro. This macro creates a new instance of WinHelp and displays the contents topic of the "Help on Help" file in the new instance. This does not effect the current instances topics.If the defined "Help on Help" file is not able to be found WINHELP.HLP will be loaded. If WINHELP.HLP is not able to be found WinHelp displays and error message and loads no file into the new instance. Example This macro displays the defined "Help on Help" file: HelpOn() See Also JumpHelpOn SetHelpOnFile HelpOnTop Toggles the on top state of WinHelp Usage HelpOnTop() Alias None Description The HelpOnTop toggles the on-top state of all windows attached to the current WinHelp instance. The Help|Always on Top menu item is changed and unchecked as required. Executing this macro is the same as selecting the Help|Always on Top menu command. Parameters None Windows MainSecondary Comments All help windows - the main window, secondary windows and the History window are affected by this macro.In WinHelp version 4.0, the HelpOnTop macro affects only the current window.You can define windows to startup in the on-top state through the Windows tab of the Project|Settings dialog.WinHelp does not provide a way to check the on-top state..A WinHelp 4.0 Help window can have three states: Default Authored as part of the window definition in the project file On Top Forced on Not On Top Forced off The latter two states, set by the user, affect all Help windows. If the user sets either the On Top or Not On Top options (from the Options menu, the Menu button, or a context menu), the HelpOnTop macro has no effect.You can use the Generate macro to send a message to WinHelp as if the user had selected a menu command. To specify the Default option, use a value of 1470 as the message parameter in the Generate macro. To set the On Top or Not On Top options, use 1471 or 1472, respectively. Example This macro toggles the on top state of all WinHelp windows: HelpOnTop() History Displays the History window. Usage History() Alias None Description The History macro displays the WinHelp History window, which shows the titles of the last 40 topics that have been displayed since this instance of WinHelp was started. Executing this macro is the same as selecting the [History] button on the button bar. Parameters None. Windows Main Comments Topics without a title will be displayed in the history list as ">> Untitled Topic <<".The number of topics kept in the history list can be changed by using the BACKTRACK switch in the Win.ini file when using WinHelp 4.0. Example This macro displays the WinHelp History Window: History() See Also Back IfThen Executes a macro if a condition is true Usage IfThen(condition, `macro') Alias IF (only in WinHelp v 4.0) Description The IfThen macro executes the macro specified if a condition is true. Parameters condition A macro that returns 1 if the condition is true, or 0 if the condition is false. macro Specifies the macro that is executed if the condition is true. Multiple macros should be separated by semicolons. Comments IfThen is most often used with IsMark to execute a macro if a particular marker exists. You can also write custom macros that test any condition and use them with this macro. Example This macro displays the Windows Clock application if the "Clock" marker exists. IfThen(IsMark(`Clock'),"ExecProgram(`clock.exe',0)") See Also DeleteMark GotoMark IfThenElse IsMark IsNotMark Not SaveMark IfThenElse Executes a macro if a condition is true, or a different macro if the condition if false. Usage IfThenElse(condition, `macrotrue', `macrofalse') Alias IE Description The IfThenElse macro executes the macrotrue macro specified if a condition is true or the macrofalse macro if the condition is false. Parameters condition A macro that returns 1 if the condition is true, or 0 if the condition is false. macrotrue Specifies the macro that is executed if the condition is true. Multiple macros should be separated by semicolons. macrofalse Specifies the macro that is executed if the condition is false. Multiple macros should be separated by semicolons. Comments IfThenElse is most often used with IsMark to execute a macro if a particular marker exists. You can also write custom macros that test any condition and use them with this macro. Example This macro displays the Windows Clock application if the "Clock" marker exists, otherwise it executes the Windows Paintbrush application: IfThenElse(IsMark(`Clock'),"ExecProgram(`clock.exe',0)", "ExecProgram(`pbrush.exe',0)") See Also DeleteMark GotoMark IfThen IsMark IsNotMark Not SaveMark InitMPrint (only in WinHelp v 4.0) Allows printing of multiple topics. Usage InitMPrint() Alias None Description The InitMPrint macro initializes WinHelp in preparation for printing multiple topics.. Parameters None Windows MainSecondary Comments This macro displays the Printer Setup dialog box. If a user clicks OK, the InitMPrint macro returns TRUE. Otherwise, it returns FALSE. This macro should be used as the first parameter in an IfThen macro to ensure that printing multiple topics occurs only if a user clicks OK. This macro does not print any topics. To print topics you must call the MPrintHash or MPrintID macros. When you have finished printing, call EndMPrint. Example This example prints the two topics whose Context Strings are "topic_a" and "topic_b": IfThen(InitMPrint(), MPrintId(topic_a); MPrintId(topic_b): EndMPrint()) See Also EndMPrint MPrintHash MPrintId InsertItem Insert an item in a WinHelp menu. Usage InsertItem(`menu-id', `item-id', `item-name', `macro', position) Alias None Description The InsertItem macro inserts an item into a WinHelp menu at a given position. Parameters menu-id A string that specifies the name assigned to the menu when it was created with the ExtInsertMenu or InsertMenu macros. The menu-id can also be one of the following standard menus: Name Menu mnu_file File mnu_edit Edit mnu_bookmark Bookmark mnu_help Help mnu_main Append the item to the end of the menu bar. mnu_floating The floating menu item-id The name that WinHelp will use internally to identify this menu item. This id can be used in the CheckItem, DeleteItem, DisableItem, EnableItem, ExtAbleItem and UncheckItem macros to manipulate the item. name A string that specifies the text that will be displayed in the menu for this item. Any character coming after an ampersand (&) will be used as the item's accelerator. To display an ampersand put && in the string. macro Specifies the macro that is executed when the button is chosen. Multiple macros should be separated by semicolons. position Specifies the numeric position of the menu item in the menu. Position 0 is the first position in the menu. Windows Main Comments When assigning an accelerator key for a menu item you must ensure that it is unique within the menu. If you assign a key that conflicts with another accelerator key, WinHelp will display an "Unable to add item" error message and the item will not be added to the menu. Example This macro inserts a menu item at the start of the Help menu that executes the Paintbrush accessory: InsertItem("mnu_help","itm_paintbrush","PaintBrush", "ExecProgram(`pbrush.exe',0)",0) See Also AppendItem ChangeItemBinding CheckItem DeleteItem DisableItem EnableItem ExtAbleItem ExtInsertItem ResetMenu UncheckItem InsertMenu Inserts a menu into the WinHelp menu bar. Usage InsertMenu(`menu-id', `menu-name', position) Alias None Description The InsertMenu macro inserts a menu at a specified position on the WinHelp menu bar. Parameters menu-id The name that WinHelp will use internally to identify this menu. This id can be used in the AppendItem, ExtInsertItem and ExtInsertMenu macros to manipulate the item. name A string that specifies the menu name. Any character coming after an ampersand (&) will be used as the item's accelerator. To display an ampersand put && in the string. position Specifies the numeric position of the menu item in the menu bar. Position 0 is the first position in the menu bar. Windows Main Comments When assigning an accelerator key for a menu item you must ensure that it is unique within the menu. If you assign a key that conflicts with another accelerator key, WinHelp will display an "Unable to add item" error message and the item will not be added to the menu. Example This macro adds a Display menu between the File and Edit menu. InsertMenu("mnu_display","Display",1) See Also ExtInsertMenu ResetMenu IsBook (only in WinHelp v 4.0) Determines whether WinHelp is running as a standalone system. Usage IsBook() Alias None Description The IsBook macro determines whether WinHelp is running as a standalone system (a double-clicked book icon), or if it is being run from a program. Parameters None Windows MainSecondary Comments This macro can be used as the first parameter of a IfThen or IfThenElse macro to take specific action depending on whether the current Help file is being run as a double-clicked book icon. The IsBook macro returns a value of TRUE if WinHelp is being run as a book; otherwise, the macro returns FALSE. Example This example displays the WinHelp About dialog box if this help file is run from a book: IfThen(IsBook(), About()) IsMark Provides a way to find out if a specific text marker exists. Usage IsMark(`marker-name') Alias None Description The IsMark macro determines whether or not a particular text marker exists and returns 1 if it does or 0 if not. Parameters marker-name A string that specifies the mark to be checked. Windows MainSecondary Comments IsMark is normally used with the IfThen and IfThenElse macros to execute macros depending on whether or not a particular text marker exists.The result of the IsMark macro can be reversed by using the Not macro. Example This macro displays the Windows Clock application if the "Clock" marker exists. IfThen(IsMark(`Clock'),"ExecProgram(`clock.exe',0)") See Also DeleteMark GotoMark IfThen IfThenElse IsNotMark Not SaveMark IsNotMark (only in WinHelp v 4.0) Tests whether or not a marker that was set by the SaveMark macro exists. Usage IsNotMark(`marker-name') Alias NM Description The IsNotMark macro determines whether or not a particular text marker exists and returns 0 if it does or 1 if not. Parameters marker-name A string that specifies the mark to be checked. Windows MainSecondary Comments The IsNotMark macro is used as a parameter in the conditional macros IfThen or IfThenElse. The result of this macro is the exact opposite of the IsMark macro that is usually used with the IfThen and IfThenElse macros. Example This macro displays the Windows Clock application if the "Clock" marker does not exist. IfThen(IsNotMark(`Clock'),"ExecProgram(`clock.exe',0)") See Also DeleteMark GotoMark IfThen IfThenElse IsMark Not SaveMark JumpContents Displays the Contents topic of the specified help file. Usage JumpContents(`filename') Alias None Description The JumpContents macro jumps to the Contents topic of the specified help file. Executing this macro is the same as opening a new help file through the File|Open dialog. Parameters filename A string that specifies the name of the help file whose Contents topic is to be displayed. Windows MainSecondary Comments If WinHelp cannot find the specified help file, an error message is displayed and no jump takes place. To make the help file appear in a secondary window, append a > and the name of the secondary window to the file name. The secondary window must be the name of a secondary window defined in the Windows tab of Project|Settings dialog of the file you are jumping to - not in the current file. Example The following macro jumps to the Contents topic of the Control Panel help file: JumpContents(`control.hlp') See Also Contents Finder SetContents JumpContext Jumps to the topic with the specified context number within the specified help file. Usage JumpContext(`filename', context-number) Alias JC Description The JumpContext macro executes a jump to the topic in the specified help file that corresponds to the specified context number. Parameters filename A string that specifies the name of the help file that contains the desired topic. context-number The context number assigned to the desired topic. The context number can be specified through the Topic Properties window. Windows MainSecondary Comments If WinHelp cannot find the specified help file an error message is displayed and no jump is executed.If the specified context number does not exist in the help file, WinHelp displays the Contents topic of the specified help file.To make the topic appear in a secondary window, append a > and the name of the secondary window to the filename. The secondary window must be the name of a secondary window defined in the Project|Settings tab of the file you are jumping to - not in the current file. Example This macro displays the topic in this help file whose Context Number is 67. The new topic is displayed in the secondary window wnd_mine: JumpContext(`macros.hlp>wnd_mine', 67) See Also JumpHash JumpId JumpKeyword PopupContext PopupHash PopupId UpdateWindow JumpHash (undocumented) Displays the topic with the specified hash number within the specified help file. Usage JumpHash(`filename', hash-number) Alias JH (only in WinHelp v 4.0) Description The JumpHash macro executes a jump to the topic in the specified help file that corresponds to the specified hash number. Parameters filename A string that specifies the name of the help file that contains the desired topic. hash-number The hash number that identifies the desired topic. Windows MainSecondary Comments A Hash number is created based on a context string. If WinHelp cannot find the specified help file, an error message is displayed and no jump is performed.If the specified hash number does not exist in the specified help file, WinHelp displays the Contents topic of the specified help file.To make the topic appear in a secondary window, append a > and the name of the secondary window to the file name. The secondary window must be the name of a secondary window defined in the Project|Settings tab of the file you are jumping to - not in the current file. Example This macro displays the topic in this help file whose hash number is 0x636A2A57. The new topic is displayed in the secondary window wnd_mine: JumpHash(`macros.hlp>wnd_mine', 0x636A2A57) See Also JumpContext JumpId JumpKeyword PopupContext PopupHash PopupId UpdateWindow JumpHelpOn Display the current "Help on Help" file. Usage JumpHelpOn() Alias None Description The JumpHelpOn macro displays the help file for the WinHelp application. Calling this macro is the same as selecting the Help|How to Use Help menu command. Parameters None Windows MainSecondary Comments The default "Help on Help" file is WINHELP.HLP (WINHLP32.HLP for WinHelp 4.0).You can change the current "Help on Help" file through the SetHelpOnFile macro.This macro creates a new instance of WinHelp and displays the contents topic of the "Help on Help" file in the new instance. This does not effect the current instances topics.If the defined "Help on Help" file is not able to be found WINHELP.HLP will be loaded. If WINHELP.HLP is not able to be found WinHelp displays and error message and loads no file into the new instance. Example This macro displays the defined "Help on Help" file: JumpHelpOn() See Also HelpOn SetHelpOnFile JumpId Displays the topic identified by the specified context string within the specified help file. Usage JumpId(`filename', `context-string') Alias JI Description The JumpId macro executes a jump to the topic in the specified help file that has the specified context string. Parameters filename A string that specifies the name of the help file that contains the desired topic. context-string A string that identifies the context string of the desired topic. Windows MainSecondary Comments If WinHelp cannot find the specified help file an error message is displayed and no jump is performed.If the specified context string does not exist in the help file, WinHelp displays the Contents topic of the specified help file.To make the topic appear in a secondary window, append a > and the name of the secondary window to the file name. The secondary window must be the name of a secondary window defined in the Project|Settings tab of the file you are jumping to - not in the current file. Example This macro displays the topic in this help file that has the context string `Jump_Example'. The new topic is displayed in the secondary window wnd_mine: JumpId(`macros.hlp>wnd_mine', `Jump_Example') See Also JumpContext JumpHash JumpKeyword PopupContext PopupHash PopupId UpdateWindow JumpKeyword Displays the first topic in the specified help file that contains the specified keyword. Usage JumpKeyword(`filename', `keyword') Alias JK Description The JumpKeyword macro searches the keyword list of the specified help file and displays the first topic that matches the specified keyword. Parameters filename A string that specifies the name of the help file that contains the desired topic. keyword A string that identifies the keyword to search for. Windows MainSecondary Comments If WinHelp cannot find the specified help file, or if the specified keyword is not found in the help file, an error message is displayed and no jump is performed. Unlike JumpContext, JumpHash, and JumpId, you cannot specify a blank filename parameter to force WinHelp to search the current file's keyword list. To make the topic appear in a secondary window, append a > and the name of the secondary window to the file name. The secondary window must be the name of a secondary window defined in the Project|Settings tab of the file you are jumping to - not in the current file. Under Winhelp 4.0 this macro is functionally equivalent to the KLink macro. Example This macro displays the first topic in this help file that contains the keyword `Jump Example'. The new topic is displayed in the secondary window wnd_mine: JumpKeyword(`macros.hlp>wnd_mine', `Jump Example') See Also JumpContext JumpHash JumpId KLink PopupContext PopupHash PopupId Search UpdateWindow KLink (only in WinHelp v 4.0) Searches for K-Keywords Usage KLink(`keyword[; keyword'] [, type[, `context-string'[, `window-name']]]) Alias KL Description The KLink macro searches for Keywords with the specified keyword within the current help file(s). Parameters keyword Specifies one or more keywords to search for. Multiple keywords must be separated by a semicolon. If any keyword contains a comma, the entire keyword string must be enclosed in quotation marks. type Specifies the action to perform if one or more keywords are found. If this parameter is not specified or is zero, the default action is always to display the Topics Found dialog box containing the topic title. This parameter may specify one or more of the following values, added together. Value Meaning 1 Specifies that if only one topic matches any of the keywords, WinHelp should jump directly to that topic. 2 Specifies that if a keyword is found in more than one Help file, WinHelp should display the title of the Help file (as specified in the contents [.cnt] file) beside the topic title in the Topics Found dialog box. 4 Specifies that the macro should return a value indicating whether or not there is at least one match. The TestKLink macro is converted by Help Workshop into an KLink macro with this parameter. context-string A string that identifies the context string of the topic to display in a pop-up window if no matches are found. If this parameter is not specified, WinHelp displays a message box with the text "No additional information is available". To specify a topic in a different Help file, the topic ID should end with an ‘@’ character and the name of the Help file. window-name Specifies the window name in which to display the topic. The window name is the name you have assigned to the window in the Windows tab of the Project|Settings dialog. For the main window, this parameter should be "main".  If this parameter is not specified, the window type that is specified for a topic (if one is defined) is used, or the default or current window is used. If this macro results in an interfile jump, the window type must be defined in the project for the Help file that is being jumped to. Windows MainSecondary Comments The KLink macro searches for A-keyword matches in the current Help file. If the Help file is associated with a contents file, WinHelp searches all Help files specified in the contents file for matching A-keywords. The KLink macro is identical to the ALink macro except that it searches for K-keywords instead of A-keywords. Example This example displays a list of topics that contain contain the "network printing" or "local printing" keywords in K-footnotes: KLink(network printing;local printing) See Also ALink TestALink TestKLink Menu (only in WinHelp v 4.0) Displays the floating menu. Usage Menu() Alias MU Description The Menu macro displays the floating menu for the current Help window. Parameters None Windows MainSecondary Comments Unlike the FloatingMenu macro, the Menu macro is carried out the moment it is encountered. If the Menu macro is used in a macro string, it may be carried out before any macros that precede it. If the current window has a Menu button, the menu will be displayed relative to that button. Otherwise, it will be displayed relative to the mouse position. Example This example displays the floating menu: Menu() See Also FloatingMenu MPrintHash (only in WinHelp v 4.0) Prints a topic identified by a hash number. Usage MPrintHash(`hash-number') Alias None Description The MPrintHash macro prints a topic identified by a hash number. Parameters hash-number The hash number that identifies the desired topic. Windows MainSecondary Comments The MPrintHash macro must be used in conjunction with the InitMPrint and EndMPrint macros. Example This example prints the two topics whose Hash numbers are 894327 and 324332: IfThen(InitMPrint(), MPrintHash(894327); MPrintHash(324332): EndMPrint()) See Also EndMPrint InitMPrint MPrintId MPrintId (only in WinHelp v 4.0) Prints a topic identified by a context string. Usage MPrintId(`context-string') Alias None Description The MPrintId macro prints a topic identified by a context string. Parameters context-string A string that identifies the context string of the desired topic. Windows MainSecondary Comments The MPrintHash macro must be used in conjunction with the InitMPrint and EndMPrint macros. Example This example prints the two topics whose Context Strings are "topic_a" and "topic_b": IfThen(InitMPrint(), MPrintId(topic_a); MPrintId(topic_b): EndMPrint()) See Also EndMPrint InitMPrint MPrintHash Next Displays the next topic in the current browse sequence. Usage Next() Alias None Description The Next macro displays next topic in the current browse sequence. Calling this macro is the same as pressing the [>>] button on the button bar. Parameters None Windows Main Comments If the currently displayed topic is the last topic in a browse sequence, or if the currently displayed topic is not part of a browse sequence, this macro is performs no action. This macro executes correctly even if there the browse buttons are not displayed. Example This macro displays the next topic in the browse sequence: Next() See Also BrowseButtons Prev NoShow (only in WinHelp v 4.0) Prevents a Help window from being displayed. Usage NoShow() Alias None Description The NoShow macro prevents a Help window from being displayed if it has not already been displayed. Parameters None Windows MainSecondary Comments None. Example This example prevents the window from being shown if it hasn't already been shown: NoShow() Not Reverses the result of a conditional macro. Usage Not(`condition') Alias None Description The Not macro reverses the result (non-zero or zero) returned by a conditional macro such as IsMark. Parameters condition A macro that returns 1 if the condition is true, or 0 if the condition is false. Windows MainSecondary Comments Not is most often used to reverse the sense of the IsMark macro, but can be used to reverse the result of any macro that returns a true or false value. Example This macro displays the Windows Clock application if the "Clock" marker does not exist. IfThen(Not(IsMark(`Clock')),"ExecProgram(`clock.exe',0)") See Also DeleteMark GotoMark IfThen IfThenElse IsMark IsNotMark SaveMark PopupContext Displays, in a popup window, the topic with the specified context number within the specified help file. Usage PopupContext(`filename', context-number) Alias PC Description The PopupContext macro displays, in a popup window, the topic in the specified help file that corresponds to the specified context number. Parameters filename A string that specifies the name of the help file that contains the desired topic. context-number The context number assigned to the desired topic. The context number can be specified through the Topic Properties window. Windows MainSecondary Comments If WinHelp cannot find the specified help file an error message is displayed and no popup window is displayed.If the specified context number does not exist in the help file, WinHelp displays the Contents topic of the specified help file. Example This macro displays in a popup window the topic in this help file whose Context Number is 68. A blank string for the filename is used to display the topic from the current help file. PopupContext(`', 68) See Also JumpContext JumpHash JumpId JumpKeyword PopupHash PopupId UpdateWindow PopupHash (undocumented) Displays, in a popup window, the topic with the specified hash number within the specified help file. Usage PopupHash(`filename', hash-number) Alias None Description The PopupHash macro displays, in a popup window, the topic in the specified help file that corresponds to the specified hash number. Parameters filename A string that specifies the name of the help file that contains the desired topic. hash-number The hash number that identifies the desired topic. Windows MainSecondary Comments A Hash number is created based on a context string.If WinHelp cannot find the specified help file, an error message is displayed and no jump is performed.If the specified hash number does not exist in the specified help file, WinHelp displays the Contents topic of the specified help file. Example This macro displays, in a popup window, the topic in this help file whose hash number is 0x3D633051. A blank string for the filename is used to display the topic from the current help file: PopupHash(`', 0x3D633051) See Also JumpContext JumpHash JumpId JumpKeyword PopupContext PopupId UpdateWindow PopupId Displays, in a popup window, the topic identified by the specified context string within the specified help file. Usage PopupId(`filename', `context-string') Alias PI Description The PopupId macro displays, in a popup window, the topic in the specified help file that has the specified context string. Parameters filename A string that specifies the name of the help file that contains the desired topic. context-string A string that identifies the context string of the desired topic. Windows MainSecondary Comments If WinHelp cannot find the specified help file, an error message is displayed and no jump is performed.If the specified context string does not exist in the help file, WinHelp displays the Contents topic of the specified help file. Example This macro displays the topic in this help file that has the context string `Popup_Example' in a popup window. A blank string for the filename is used to display the topic from the current help file: PopupId(`', `Popup_Example') See Also JumpContext JumpHash JumpId JumpKeyword PopupContext PopupHash UpdateWindow PositionWindow Sets the size and position of a help window. Usage PositionWindow(x, y, width, height, state, `name') Alias PW Description The PositionWindow macro sets the size, position, and display state of any help window. Parameters x An integer that specifies the new x-coordinate, in help units, of the upper-left corner of the window. y An integer that specifies the new y-coordinate, in help units, of the upper-left corner of the window. width An integer that specifies the new width, in help units, of the window. height An integer that specifies the new height, in help units, of the window. state An unsigned integer that specifies the window's new display state. This parameter is passed on to Windows ShowWindow API. It accepts any of the following values: Value Meaning 0 Hide the window. The position and size parameters are ignored. 1 Position and display the window. If the window is minimized or maximized, then activate it after it has been displayed. 2 Activate the window and minimize it. The position and size parameters are ignored. 3 Activate the window and maximize it. The position and size parameters are ignored. 4 Position, but do not activate, the window. 5 Position, but do not activate, the window. If the window is minimized or maximized, no action is taken. 6 Minimize the window and activate the top-level window in the system's list. This may cause the current help window to be hidden by the window that gets displayed. The position and size parameters are ignored. 7 Minimize the window. The current window remains active. The position and size parameters are ignored. 8 Position the window and show it in its current state, but do not activate the window. If the window is minimized or maximized, the position and size parameters are ignored and the window is displayed in its current state. name A string that specifies the name of the help window that is to be positioned. This is the name you have assigned to the window in the Windows tab of the Project|Settings dialog. The main window can be positioned by setting this parameter to `main'. Windows MainSecondary Comments Regardless of the actual display resolution, WinHelp always assumes that the display is 1,024 help units wide and 1,024 help units high. For example, (x,y) values of (512,512) will position the upper left corner of the help window in the center of the screen. Although PositionWindow may activate a window in some cases, it never focuses (i.e. passes control of keyboard input to) a window. If the specified window does not exist, WinHelp ignores this macro. Example This macro positions the main help window to the upper left of the screen and sizes it so that it occupies half of the display: PositionWindow(0, 0, 512, 512, 1, `main') See Also CloseSecondarys CloseWindow FocusWindow Prev Display the previous topic in the current browse sequence. Usage Prev() Alias None Description The Prev macro displays previous topic in the current browse sequence. Executing this macro is the same as pressing the [<<] browse button on the button bar. Parameters None Windows Main Comments If the currently displayed topic is the first topic in a browse sequence, or if the currently displayed topic is not part of a browse sequence, this macro does nothing.This macro executes correctly even if there the browse buttons are not displayed. Example This macro displays the previous topic in the current browse sequence: Prev() See Also BrowseButtons Next Print Prints the current topic. Usage Print() Alias None Description The Print macro prints the currently displayed topic on the printer. Calling this macro is the same as selecting File|Print Topic menu command. Parameters None Windows MainSecondary Comments The topic is printed to the printer currently selected in the Print Setup dialog, which can be accessed through the File|Print Setup menu command or through the PrinterSetup macro. If this macro is executed from a popup window, the topic that contains the popup link, not the popup topic itself, is printed. Under WinHelp 4.0 this macro displays the Printer Setup dialog before printing. Example This macro prints the current topic: Print() See Also EndMPrint InitMPrint MPrintHash MPrintId PrinterSetup PrinterSetup Displays the Printer Setup dialog box. Usage PrinterSetup() Alias None Description The PrinterSetup macro displays the Print Setup dialog box. Calling this macro is the same as to selecting the File|Print Setup menu command. Parameters None Windows MainSecondary Comments This macro is obsolete under WinHelp 4.0. WinHelp always displays the Print Setup dialog box before printing. Example This macro displays the PrinterSetup dialog PrinterSetup() See Also Print RegisterRoutine Registers a function in a Dynamic Link Library (DLL) as a custom help macro. Usage RegisterRoutine(`DLL-name', `function-name', `format-details') Alias RR Description The RegisterRoutine macro registers a function within a DLL as a custom help macro. The custom help macro can be used in the same way you use standard Winhelp macros. Parameters DLL-name A string that specifies the file name of the DLL that contains the function to be registered. If the .DLL extension is not included in this name WinHelp will add it. function-name A string that specifies the function's name within the DLL. When finding the function in the DLL windows is not case sensitive. E.g: `MyCustomMacro' and `MYCUSTOMMACRO' are considered to the be same function. format-details A string that defines the number and types of parameters to be passed to the function. This string may contain any of the following characters: Character Parameter Type u An unsigned short integer U An unsigned long integer i A signed short integer I A signed long integer s A near (16-bit) string pointer S A far (32-bit) pointer to a null-terminated character string v No type. Used only with return values. = Specifies the return value type The help compiler will validate the parameters passed to a custom macro to ensure that they are the proper types, and will produce an error message if the parameter types are incorrect. Windows MainSecondary Comments If WinHelp cannot find the DLL, an error message is issued and the macro is not defined. Normally RegisterRoutine should be executed from the Macros tab in the Project|Settings dialog so that the macro can be called from anywhere in the help file. It is recommended that you include the .dll filename extension when specifying the name of the DLL. Without the extension, WinHelp first looks through all its various folders trying to find the file exactly as specified. Only after this fails does it add the .dll extension and look through all t he search paths again. Functions in 32-bit DLLs must use the _stdcall calling convention. Functions in 16-bit DLLs (which are not available when running Windows NT) must the _pascal calling convention. Example The following macro registers a function called MyCustomMacro in the DLL MYDLL.DLL. MyCustomMacro accepts a single string parameter and returns non-zero if the number is odd, or zero if the number is even: RegisterRoutine(`mydll',`MyCustomMacro',`i=S') RemoveAccelerator Removes a previously assigned accelerator key combination. Usage RemoveAccelerator(key, shift-state) Alias RA Description The RemoveAccelerator macro removes an accelerator key or key combination that was previously assigned with the AddAccelerator macro. Parameters key Specifies the key code. shift-state Specifies the combination of Shift, Ctrl, and Alt keys that was used in combination with key. This parameter may be one of the following values Value Modifier keys 0 None 1 Shift 2 Ctrl 3 Shift+Ctrl 4 Alt 5 Alt+Shift 6 Alt+Ctrl 7 Shift+Alt+Ctrl Windows MainSecondary Comments No error message is displayed if an attempt is made to remove an accelerator that hasn't been defined. Example This macro removes the previously defined CTRL+V accelerator key combination: RemoveAccelerator(0x56, 2) See Also AddAccelerator ResetMenu (undocumented) Returns the WinHelp menu to its default state. Usage ResetMenu() Alias None Description The ResetMenu macro returns the WinHelp menu bar and all popup menus to their default values. Parameters None Windows MainSecondary Comments Executing this macro deletes all added menus and menu items, restores any standard menu items that were deleted, enables all standard menu items, and restores the item bindings of all standard menu items to their defaults. The floating menu is cleared. Example This macro restores the WinHelp menus to their default: ResetMenu() See Also AppendItem ChangeItemBinding CheckItem DeleteItem DisableItem EnableItem ExtAbleItem ExtInsertItem InsertItem UncheckItem SaveMark Creates a text marker. Usage SaveMark(`marker-name') Alias None Description The SaveMark macro saves information about the currently displayed topic, and associates a text marker with that location. Text markers are used by the GotoMark and IsMark macros. Parameters marker-name A string that specifies the name of the mark to be created. If marker-name has already been defined, it is redefined at the new location. Windows MainSecondary Comments If the marker-text was already used, the SaveMark macro replaces the information associated with the previously saved marker-text. When the user quits WinHelp, all text markers are deleted. The SaveMark macro is carried out as soon as it is encountered. If you use it in a macro string, it may be carried out before any macros that precede it. Example This macro creates the text marker `Clock' at this location in this topic: SaveMark(`Clock') See Also DeleteMark GotoMark IfThen IfThenElse IsMark IsNotMark Not Search Displays the search dialog box. Usage Search() Alias None Description The Search macro displays WinHelp's Search dialog box. Calling this macro is equivalent to pressing the [Search] button on the WinHelp button bar. Parameters None Windows Main Comments Calling this macro from a help file that contains no keywords will produce unpredictable results. Example This macro displays the Search dialog: Search() See Also JumpKeyword SetContents Sets the contents topic of the current help file Usage SetContents(`filename', context-number) Alias None Description The SetContents macro sets the topic that is to be displayed when the Contents button is pressed. Parameters filename A string that specifies the name of the help file that contains the new Contents topic. context-number Specifies the context number of the topic that is to be used as the Contents topic. The context number can be specified through the Topic Properties window. Windows MainSecondary Comments The SetContents macro has no effect if the filename parameter specifies a file other than the one that is currently being displayed. If the specified context number does not exist, WinHelp will display an error when the Contents button is clicked. Changing the contents topic using this macro does not affect the compiled help file - the contents topic set in the Project|Settings dialog is always used unless this macro is called first. Example This macro sets the topic with context number 67 as the Contents topic: SetContents(`macros.hlp', 67) See Also Contents JumpContents SetHelpOnFile Specifies the current "Help on Help" file. Usage SetHelpOnFile(`filename') Alias None Description The SetHelpOnFile macro specifies the current "Help on Help" file, which is displayed when the reader selects the Help|How to Use Help menu command, or when the HelpOn or JumpHelpOn macros are executed. Parameters filename A string that specifies the name of the replacement "Help on Help" file. Windows MainSecondary Comments The default "Help on Help" file is WINHELP.HLP.To make the help file appear in a secondary window, append a > and the name of the secondary window to the file name. The secondary window must be the name of a secondary window defined in the Project|Settings tab of the file you are jumping to - not in the current file.This macro is obsolete in WinHelp 4.0. WinHelp version 4.0 will ignore this macro. Example This macro sets the "Help on Help" file to HWAWIN.HLP: SetHelpOnFile(`hwawin.hlp') See Also HelpOn JumpHelpOn SetPopupColor (only in WinHelp v 4.0) Sets the background color of popups. Usage SetPopupColor(r, g, b) Alias SPC Description The SetPopupColor macro sets the background color for all subsequent pop-up windows. Parameters r Specifies the red component of the color. This value is an integer in the range 0 to 255. g Specifies the green component of the color. This value is an integer in the range 0 to 255. b Specifies the blue component of the color. This value is an integer in the range 0 to 255. Windows MainSecondary Comments After this macro is run, the set color applies to all pop-up topics. Example This macro sets the background color for pop-up windows to blue: SetPopupColor(0, 0, 255) ShellExecute (only in WinHelp v 4.0) Opens or prints the specified file. Usage ShellExecute(`filename', [options[, show-flag[, operation[, path[, `context-string']]]]]) Alias SE Description The ShellExecute macro displays opens or prints the specified file. Parameters filename Specifies the name of the file to open. options Specifies parameters passed to the program when the filename parameter specifies an executable (.exe) file. If the filename parameter specifies a document file, this parameter is empty. show-flag Specifies how the program is shown when it is opened. If the filename parameter specifies a document file, this parameter should be zero. Value Meaning 0 Hides the window. 3 Activates the window and maximizes it. 6 Activates the window and minimizes it. 7 Minimizes the window, but WinHelp keeps the focus. 4 Displays a window in its current state, but WinHelp keeps the focus. (If the window was minimized before this call, it stays minimized.) 5 Activates the window and displays it in its current size and position. 9 Restores the window to its original size and position if the window is minimized or maximized. operation Specifies the operation to perform. This parameter can be "open" or "opencpl" or "print". If this parameter is not specified, "open" is the default value. path Specifies the default folder. Use "" if you do not need to specify a default folder. context-string A string that identifies the context string of the desired topic. Windows MainSecondary Comments The filename can be a document file or an executable file. If it is a document file, this function opens or prints it, depending on the value of the operation parameter. If it is an executable file, this function opens it, even if the operation parameter specifies print. If no path is specified with the filename, WinHelp uses the standard search algorithm.The ShellExecute macro calls the Windows ShellExecute function. Example This example displays the WinHelp About dialog box: About() See Also ExecFile ShortCut (only in WinHelp v 4.0) Runs the specified program if it is not already running. Usage ShortCut(`window-class', `program'[, wParam[, lParam[,  `context-string']]]) Alias SH Description The ShortCut macro runs the specified program if it is not already running. If the specified program is running, WinHelp activates it. If the wParam parameter is specified, a WM_COMMAND message with the specified wParam and lParam values are sent to the program. Parameters window-class Specifies the class name of a top level window of the program. WinHelp uses this class name to determine if the program is already running. program Specifies the executable name of the program. This is the name of the program that runs if the window class name cannot be found. The .exe extension does not need to be included. wParam Specifies the first argument to the WM_COMMAND message that is sent to the program. If this value is not specified, the program is started, but no message is sent and the program is not activated. lParam Specifies the second argument to the WM_COMMAND message. context-string Specifies the context string of the topic to jump to if the program cannot be found. If this parameter is not specified, WinHelp displays a message box indicating that the program could not be found. If it is specified and no filename is included, the filename specified by the :Base command in the contents (.cnt) file is used. If there is no associated contents file, the current Help file is used. To specify a specific filename, the topic ID should end with an '@' character and the name of the Help file. Windows MainSecondary Comments If you need to include a context string, but do not want to send the program any messages, you can either use -1 for the wParam argument and 0 for the lParam argument, or you can simply include the commas without specifying the values for the arguments as follows: ShortCut(class_name, myapp, , , context-string) Some programs, such as the Microsoft Visual C++ compiler (MSVC), cannot receive a message in the same call that runs them. In this case, you must first call the ShortCut macro without specifying wParam or lParam. You can then call this macro again and send the wParam and lParam messages. Note that the second time you call this macro, you can use an empty string ("") for the program name. Example The following example copies the current topic to the Clipboard, runs or activates Notepad, and pastes the text from the Clipboard into Notepad: CopyTopic():ShortCut(notepad, notepad, 0x0302) TCard (only in WinHelp v 4.0) Sends a message to the program that is invoking WinHelp as a training card. Usage TCard(command) Alias None Description The TCard macro sends a message to the program that is invoking WinHelp as a training card. Parameters command Specifies one of the following commands or a numeric value. If one of the following values is specified, its numeric equivalent is sent as the wParam value of the WM_TCARD message: Value Meaning IDABORT (3) The user clicked an authorable Abort button. IDCANCEL (2) The user clicked an authorable Cancel button. IDCLOSE (8) The user closed the training card. IDHELP (9) The user clicked an authorable Help button. IDIGNORE (5) The user clicked an authorable Ignore button. IDOK (1) The user clicked an authorable OK button. IDNO (7) The user clicked an authorable No button. IDRETRY (4) The user clicked an authorable Retry button. IDYES (6) The user clicked an authorable Yes button. Windows MainSecondary Comments If a numeric value is used, the training card program is sent HELP_TCARD_DATA (16) for the wParam parameter, and the numeric value is passed as the lParam value of the WM_TCARD message. Example This example sends a close message to the program invoking WinHelp as a training card: TCard(IDCLOSE) Test (only in WinHelp v 4.0) Runs an internal WinHelp test. Usage Test(test-num) Alias None Description The Test macro runs an internal WinHelp test. Parameters test-num Specifies the testing option. This parameter can be one of the following values: Value Description 1 Displays all the topics in the Help file, starting with the current topic. 2 Displays all the topics in the Help file, starting with the first topic. 3 Continuously displays all the topics in the Help file, starting with the first topic. 4 Displays all the topics in the Help file, starting with the first topic, and then quits. 5 Jumps to all topics specified in the contents file excluding macros. 6 Jumps to all topics specified in the contents file, excluding macros, and then quits. 7 Turns on Help Mode for the current instance of WinHelp only, and then launches a second instance of WinHelp on the same Help file. Both instances of WinHelp resize their windows so they can appear side-by-side and both display the first topic in the current Help file. Moving through one file (using CTRL+SHIFT commands) updates both windows. The functionality is the same as the Compare macro. Windows MainSecondary Comments You can add your own text to the About dialog box by entering some text in the Copyright box in the Options tab of the Project|Settings dialog. Example This example displays the WinHelp About dialog box: About() See Also TestALink TestKLink TestALink (only in WinHelp v 4.0) Tests whether an ALink macro has an effective link to at least one topic. Usage TestALink(`keyword[; keyword]') Alias None Description The TestALink macro tests whether a ALink macro has an effective link to at least one topic. Parameters keyword Specifies one or more A-Keywords to search for. Separate multiple keywords using semicolons. If a keyword contains a comma, enclose the entire keyword string in quotation marks. Windows MainSecondary Comments The TestKLink macro is typically used as the first parameter in an IfThen or IfThenElse macro. Help Workshop converts this macro into a KLink macro with a TEST parameter.If an effective link is found, TestALink returns a value of 1. Example The following macro enables or disables a SeeAlso button, depending on whether at least one topic contains a "print" A-keyword: IfThenElse(TestALink(`print'), ChangeEnable(`btn_seealso', ALink(print)), DisableButton(`btn_seealso')) See Also Test TestKLink TestKLink (only in WinHelp v 4.0) Tests whether a KLink macro has an effective link to at least one topic. Usage TestKLink(`keyword[; keyword]') Alias None Description The TestKLink macro tests whether a KLink macro has an effective link to at least one topic. Parameters keyword Specifies one or more Keywords to search for. Separate multiple keywords using semicolons. If a keyword contains a comma, enclose the entire keyword string in quotation marks. Windows MainSecondary Comments The TestKLink macro is typically used as the first parameter in an IfThen or IfThenElse macro. Help Workshop converts this macro into a KLink macro with a TEST parameter.If an effective link is found, TestALink returns a value of 1. Example The following macro enables or disables a SeeAlso button, depending on whether at least one topic contains a "print" keyword: IfThenElse(TestKLink(`print'), ChangeEnable(`btn_seealso', KLink(print)), DisableButton(`btn_seealso')) See Also Test TestALink UncheckItem Removes a check mark from a menu item. Usage UncheckItem(`menu-id') Alias UI Description The UncheckItem macro removes the check mark () that was previously placed beside a help menu item by the CheckItem macro. Parameters item-id A string that specifies the name specified when the menu item was created with the AppendItem, ExtInsertItem or InsertItem macro, or one of the following standard items: Id Menu Item mnu_helpon Help|How to Use Help mnu_helpontop Help|Always on Top Windows Main Comments To add a check mark, execute the CheckItem macro Example This macro removes the check mark previously placed next to the menu item created with the identifier of `itm_paintbrush'. UncheckItem(`itm_paintbrush') See Also AppendItem ChangeItemBinding CheckItem DeleteItem DisableItem EnableItem ExtAbleItem ExtInsertItem InsertItem ResetMenu UpdateWindow (only in WinHelp v 4.0) Jumps to a a topic in a secondary window without giving the focus to that window. Usage UpdateWindow(filename', `context-string')) Alias UW Description The UpdateWindow macro displays the WinHelp About dialog box. Parameters filename A string that specifies the name of the help file that contains the desired topic.context-stringA string that identifies the context string of the desired topic. Windows MainSecondary Comments If the secondary window was not already created, the UpdateWindow macro is ignored.This macro is usually used in an entry macro to update the secondary window whenever the topic is shown. To make the topic appear in a secondary window, append a > and the name of the secondary window to the file name. The secondary window must be the name of a secondary window defined in the Project|Settings tab of the file you are jumping to - not in the current file. Example This macro displays the topic in this help file that has the context string `Jump_Example'. The new topic is displayed in the secondary window wnd_mine and focus is returned to this window: UpdateWindow(`macros.hlp>wnd_mine', `Jump_Example') See Also JumpContext JumpHash JumpId JumpKeyword PopupContext PopupHash PopupId ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The WinHelp API function ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The WinHelp function starts Windows Help (WINHELP.EXE) and passes additional data indicating the nature of the help requested by the application. BOOL WinHelp( HWND hWndMain, LPCTSTR lpszHelp, UINT uCommand, DWORD dwData } hWndMain is the handle of the window requesting Help. The WinHelp function uses this handle to keep track of which applications have requested Help. If the uCommand parameter specifies HELP_CONTEXTMENU or HELP_WM_HELP, hWndMain identifies the control requesting Help. lpszHelp is the address of a null-terminated string containing the path, if necessary, and the name of the help file that WinHelp is to display. The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project (.HPJ) file. uCommand specifies the type of help requested. For a list of possible values and how they affect the value to place in the dwData parameter, see the Remarks section. dwData specifies additional data. The value used depends on the value of the uCommand parameter. For a list of possible values, see the Remarks section. If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks Before closing the window that requested Help, the application must call WinHelp with the uCommand parameter set to HELP_QUIT. Until all applications have done this, Windows Help will not terminate. Note that calling Windows Help with the HELP_QUIT command is not necessary if you used the HELP_CONTEXTPOPUP command to start Windows Help. uCommand and dwData values The following table shows the possible values for the uCommand parameter, its value, its action, and the corresponding formats of the dwData command: HELP_COMMAND (0x102) executes a Help macro or macro string. dwData is the address of a string that specifies the name of the Help macro(s) to run. If the string specifies multiple macro names, the names must be separated by semicolons. You must use the short form of the macro name for some macros because Windows Help does not support the long name. HELP_CONTENTS (3 or 0x003) displays the topic specified by the Contents option in the [OPTIONS] section of the .HPJ file. This command is for backward compatibility. New applications should provide a .CNT file and use the HELP_FINDER command. dwData is ignored. Set it to 0. HELP_CONTEXT (1 or 0x001) displays the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file. dwData is an unsigned long integer containing the context identifier for the topic. HELP_CONTEXTMENU (10 or 0x00A) displays the Help menu for the selected window, then displays the topic for the selected control in a pop-up window. dwData is the address of an array of double word pairs. The first double word in each pair is a control identifier, and the second is a context number for a topic. HELP_CONTEXTPOPUP (8 or 0x008) displays the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file in a pop-up window. dwData is an unsigned long integer containing the context identifier for a topic. HELP_CONTEXTNOFOCUS (0x108) displays the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file. dwData is an unsigned long integer containing the context identifier for the topic. WinHelp does not change the focus to the window displaying the topic. This command constant is not defined anywhere except in Jim Mischel's book, so if you want to use it you have to define the constant. HELP_POPUPID (0x104) displays the topic identified by the specified context string in a pop-up window. dwData is a pointer to a null terminated string that contains the context string of the topic to be displayed. If the main Help window is currently open it becomes the focused window. If the main Help window is not open the pop-up topic appears but the main Help window is not displayed (from Jim Mischel). This constant is not listed by MS, so you probably have to define it in your project. HELP_FINDER (11 or 0x00B) displays the Help Topics dialog box. dwData is ignored. Set it to 0. HELP_FORCEFILE (9 or 0x009) ensures that Windows Help is displaying the correct help file. If the incorrect help file is being displayed, Windows Help opens the correct one; otherwise, there is no action. dwData is ignored. Set it to 0. HELP_HELPONHELP (4 or 0x004) displays help on how to use Windows Help, if the WINHLP32.HLP file is available. dwData is ignored. Set it to 0. HELP_INDEX (3 or 0x003) is the same as HELP_CONTENTS. HELP_KEY (0x101) displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index with the topics listed in the Topics Found list box. dwData is the address of a keyword string. Multiple keywords must be separated by semicolons. HELP_MULTIKEY (0x0201) displays the topic specified by a keyword in an alternative keyword table. dwData is the address of a MULTIKEYHELP structure that specifies a table footnote character and a keyword. HELP_PARTIALKEY (0x0105)displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Topics Found dialog box. To display the Index without passing a keyword, you should use a pointer to an empty string. dwData is the address of a keyword string. Multiple keywords must be separated by semicolons. HELP_QUIT (2 or 0x0002) informs Windows Help that it is no longer needed. If no other applications have asked for Help, Windows closes Windows Help. dwData is ignored. Set it to 0. HELP_CLOSEWINDOW (0x0107) Closes the specified window. dwData is ignored. Set it to 0. To close a secondary window append the > character and the name of the secondary window to the file name passed in the lpszHelp parameter. HELP_SETCONTENTS (5 or 0x0005) specifies the Contents topic. Windows Help displays this topic when the user clicks the Contents button if the help file does not have an associated .CNT file. dwData is an unsigned long integer containing the context identifier for the Contents topic. HELP_SETINDEX (5 or 0x0005) is the same as HELP_SETCONTENTS. HELP_SETPOPUP_POS (13 or 0x000D) sets the position of the subsequent pop-up window. dwData is the address of a POINTS structure. The pop-up window is positioned as if the mouse cursor were at the specified point when the pop-up window is invoked. HELP_SETWINPOS (0x0203)displays the Help window, if it is minimized or in memory, and sets its size and position as specified. dwData is the address of a HELPWININFO structure that specifies the size and position of either a primary or secondary Help window. HELP_TCARD (0x8000) indicates that a command is for a training card instance of Windows Help. Combine this command with other commands using the bitwise OR operator. dwData depends on the command with which this command is combined. HELP_TCARD_DATA (16 or 0x0010) HELP_TCARD_OTHER_CALLER (17 or 0x0011) HELP_WM_HELP (12 or 0x000C) displays the topic for the control identified by the hWndMain parameter in a pop-up window. dwData is the address of an array of double word pairs. The first double word in each pair is a control identifier, and the second is a context identifier for a topic. For use with custom tabs in the Help Topics dialog box Constant Definition MSG_TAB_CONTEXT WM_USER + 38 MSG_TAB_MACRO WM_USER + 39 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ The WinHelp command line ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ WinHelp.exe Command line Switches winhelp.exe [-i topicID] [-n topicNumber] helpFile -i topicName specifies the topic to open using a topic ID string (# footnote in the topic). This command cannot be used with -n. -n topicNumber specifies the topic to open using a topic number, which must be defined in the [MAP] section of the HPJ file. This command cannot be used with -i. helpFile specifies the file name of the Help file. If you are not calling WinHelp from the directory with the Help file, this must be a full path and file name. Note: Starting WinHelp outside Windows 3.1 will launch Windows 3.1 and open the requested file. Winhlp32.exe command-line switches winhlp32.exe [[-H] [-G[n]] [-W window] [-K keyword] [-P pop-up] [-N contextNum] [-I topicID] helpFile] -H displays the Winhlp32.hlp Help file. -G[n] creates a configuration (.gid) file and quits. If a number is specified, it determines which extensible tab to display by default the first time the Help file is opened. A value of 1 would be the first tab beyond the Find tab. This command cannot be used with -S. -S creates a configuration (.gid) file without showing an animated icon. This command cannot be used with -G. -W window specifies the window in which the help topic will be displayed. This command cannot be used with -P. -P  pop-up specifies that the window will be shown in a pop-up window. This command cannot be used with -W. -K  keyword specifies the topic to open using a keyword. This command cannot be used with -I or -N. -N  contextNum specifies the topic to open using a topic number, which must be defined in the [MAP] section of the HPJ file. This command cannot be used with -I or -K. -I  topicID specifies the topic to open using a topic ID string (# footnote in the topic). This command cannot be used with -N or -N. helpFile specifies the file name of the Help file to open. Unless you are calling WinHelp from the directory with the Help file, this must be a full path and file name. If you don't specify a Help file, the File Open dialog box appears. Note: If you use long file names with spaces, you must enclose the entire path and file name in quotes. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Rules for using WinHelp macros ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Authors must follow these rules when constructing Help macros: Help macros are case-sensitive. A single macro string may include more than one Help macro. Use a semi-colon to separate each macro in the macro string. Specify empty spaces in a macro string by placing the surrounding text in quotation marks. Insert special characters in a quotation-marked string by prefacing the character with a backslash. Special characters include single quotation marks ("), opening and closing single quotation marks (` '), and backslashes (\). Note that the single open quotation mark is different from the single close quotation mark. The single open quotation mark (`) is paired with the tilde (~) above the TAB key on extended keyboards; the single close quotation mark (') is the same as the apostrophe. Quotation marks may be either matching double quotation marks, or a matched set of single open and single close quotation marks. If a string is enclosed in double quotation marks, any strings enclosed within the string must be enclosed in opening and closing single quotation marks. For example, CreateButton("time_btn", "&Time", "ExecProgram("clock", 0)") is illegal because the string "clock" uses double quotation marks within the double quotation marks used for the ExecProgram macro. The following example corrects the error by enclosing `clock' in single quotation marks: CreateButton("time_btn", "&Time", "ExecProgram(`clock', 0)") Macros may be included within other macros (that is, used as a parameter value for another macro). A single macro must be 254 or fewer characters in length.