This chapter describes how you can access and use the Windows Help facility from a Smalltalk/V Windows application. The user interface to Help from Smalltalk/V Windows is identical to that found by accessing Windows Help directly without using Smalltalk/V Windows. This document assumes that the reader is familiar with the process of supporting Help in MS Windows (For more information on this, refer to MS Windows SDK manuals).
To understand the Help Manager user interface, install the Puzzle15 puzzle found in your Smalltalk/V Windows EXAMPLES\PUZZLE15 directory. This puzzle has been enhanced to illustrate Help features, as follows:
1.Press the Help key F1; a help window displays extended help for Puzzle15. A Help menu has been added to the end of the menu bar.
2.Select the Help Contents menu item. It lists all the help topics available for Puzzle15.
3.Press and hold the left mouse button over the Puzzle menu in the menu bar and press the F1 key. A help window displays, describing the Puzzle menu commands. Then, drag the mouse to the Scramble menu item, press the F1 key, and a help window displays that describes Scramble menu item.
4.Choose the Select Colors... menu item from the Puzzle menu, and a dialog window opens. Press F1 without selecting anything in the dialog window, and a help window displays the help window for the whole dialog window. Next, select one of the combo boxes and press F1. An appropriate help window displays.
To include Help in your application, do the following:
1.Using any compatible text editor, compose your help text into an .RTF file. Details are given below on how to identify your panels. Compile the .RTF file into a .HLP file using Help Compiler from the Software Development Kit.
When writing your help panels, identify them according to following:
The context string of a menu is its menu title.
The context string of a menu item is its selector.
The context string of a subpane is its name (defined by #getContents event or by sending the setName: message to it).
The context string of a DialogBox is defined by the application at runtime by the sending the extendedHelpPanelId: message the HelpManager instance before opening the DialogBox or DialogTopPane.
The context string of a control in a DialogBox is the name of the item as specified in the ItemIds dictionary of the subclass of DialogBox.
The context string of TopPane and its subclass is the HelpIndex topic. This default topic can be changed by sending the extendedHelpPanelId: to the helpManager instance.
2.In the open: method for your application, create an instance of HelpManager.
Details are given below.
Creating an Instance of HelpManager before you do self openWindow, create an instance of HelpManager in your open method by sending the message #for:title:file: to HelpManager. For example,
hm := HelpManager
for: self mainView
title:nil
file: 'puzzle15.hlp'.
hm mapDictionary: aMapDictionary
In this example, it is assumed that the application is a subclass of ViewManager and it has only one view. The #for:title:file: message needs to be sent once for each view, passing that view as the parameter of for: While each view of the ViewManager has a different HelpManager associated with it, the help file associated with each of them is the same.
"Answer an instance of the receiver initialized for aWindow with aString as its title and whose help file is in aFileName (a .HLP file). Under Windows, aString is ignored
HelpManager class>>for: aWindow title: aString file: aFileName dialogs: aCollection
"Answer an instance of the receiver initialized
for aWindow with aString as its title and whose help file is in aFileName (a .HLP file). aCollection must contain the dialog box ids for the application.
Under Windows aString and aCollection are ignored
HelpManager class>>for: aWindow title: aString file: aFileName dialogs: aCollection aboutDlgClass: aboutDlg
"Answer an instance of the receiver initialized
for aWindow with aString as its title and whose help file is in aFileName (a .HLP file). aCollection must contain the dialog box ids for the application. aboutDlg is a class which implements an open instance method creating the about dialog.
Under Windows aString and aCollection areignored"
"Brings up the Windows Help for the topic defined by anId.anId can be either a string, an Integer or nil"
"Answer the default topic It can be either a string, an integer or nil"
"Set the default topic to anId.
anId can be either a string, an integer or nil"
HelpManager>>map:aDictionary
"Set the receiver's map dictionary The keys are the context strings defined in the RFT help file The values are integer defined in the include file used by the Microsoft Help Compiler"
"Answer the receiver's map dictionary The keys are the context strings defined in the RFT help file The values are integer defined in the include file used by the Microsoft Help Compiler"
To create the map dictionary use
StringDictionaryReader class>>createIdDictionary: aFileName
"Create a string identifier dictionary from a text file aFileName with dictionary keys being string identifiers and values being integer values. Contents of aFileName must be in standard C Language (.H) header file format."
aFileName should be the include file you use in your help project file (.hpj)
A late bug was discovered with associating help panels with controls inside a subclass of DialogBox. If your application needs to do this, file in the following two methods:
!UserDLL methods !
getDlgCtrlID: hWnd
!DialogBox methods !
wmHelp: wordInteger with: longInteger
ifTrue:[^super wmHelp: wordInteger with: longInteger].
wordInteger = MsgfDialogbox ifTrue:[ name := self itemIds at:
(UserLibrary getDlgCtrlID: focusWindow asParameter) ifAbsent:
[nil]. self helpManager displayHelp: name].! !
Once you file in these methods, to associate a help
panel with a control in a subclass of DialogBox, you simply use
the control id of the control (as defined in the ItemIds dictionary)
as the context string in your help text file.