About this chapter
This chapter describes how to provide online help for other PowerBuilder developers and for end users on Windows.
About help authoring tools
There are many authoring tools and related products available for creating online help files on Windows. All of the authoring tools for Microsoft HTML Help files use the Microsoft HTML Help compiler (hhc.exe) to generate a finished help file.
What to include
The source files for any help system typically include:
-
Topic files (HTML) contain the text of your help system as well as footnote codes and commands that serve to identify the topics and provide navigation and other features.
-
Graphics files contain images associated with specific topics.
-
Project file (HHP) defines a single help collection and contains instructions for the compiler.
-
Contents file (HHC) provides the entries that populate the Contents tab of the help window.
-
Index file (HHK) provides index keywords that the author provides, similar to a traditional book index, that link to specific topics.
For each project, the compiler generates a single CHM file that can be opened in an HTML Help window.
How to proceed
If you are using a full-featured Help authoring tool, follow its instructions for creating the necessary source files and compiling them. The HTML Help Workshop, available from Microsoft with the HTML Help compiler, also has help describing how to author help and how to implement it in a Windows application.
Sample project file
For your convenience, the text of a sample project file is provided here. (It is also in one of the topics of the PBUSR.CHM file that is installed with PowerBuilder.)
;*******************************************
; Sample HTML Help project file
; Use a semicolon (;) to start a comment
; Replace filenames and other options with values
; for your project.
;*******************************************
[OPTIONS]
Binary TOC=No
Binary Index=Yes
Compiled File=project.chm
Contents File=project.hhc
Index File=project.hhk
Default Window=main
Default Topic=doc/html/welcome.html
Default Font=
Flat=No
Full-text search=Yes
Auto Index=Yes
Language=
Title=Our Application Help
Create CHI file=No
Compatibility=1.1 or later
Error log file=project.log
Full text search stop list file=
Display compile progress=Yes
Display compile notes=Yes
[WINDOWS]
main="Our Application Help","project.hhc","project.hhk",
"doc/html/welcome.html","doc/html/welcome.html",,,,,
0x23520,222,0x1846,[10,10,640,450],0xB0000,,,,,,0
[FILES]
doc/html/pbusr.html
doc/styles/main.css
doc/images/logo.pngTo use the sample project file:
-
Copy the help project code to the Windows clipboard.
-
Open a text editor (like Notepad, not a word processor like Word or Wordpad) and paste the clipboard text into a blank document.
Alternatively, open the project file in your favorite HTML Help authoring tool.
-
Save the document in text format as PBUSR.HHP.
Edit your project file to specify the details of your help development environment, such as source file names and directory path names. For details, see the instructions in the HTML Help Workshop or your help authoring tool.
You can provide your own online help for your user-defined functions, user events, and user objects into the PowerBuilder development environment.
How context-sensitive help for user-defined functions works
When you select the name of a function or place the cursor in the function name in the Script view and press Shift + F1:
-
PowerBuilder looks for the standard prefix (the default is uf_) in the function name.
-
If the standard prefix is found, PowerBuilder looks for the help topic in the help file containing your user-defined function help topics (instead of looking in PBUSR.CHM, its own main help file). The default file name for help on user-defined functions is PBUSR.CHM.
PowerBuilder determines the name of the help file to look in by reading the UserHelpFile variable in PB.INI. For information on changing the value of this variable, see Advanced procedures.
-
If PowerBuilder finds the variable, it looks in the specified help file for the name of the selected function. If there is no UserHelpFile variable in PB.INI, PowerBuilder looks for the keyword in the PBUSR.CHM file in the PowerBuilder Help directory.
Simplest approach
If you work within the PowerBuilder defaults:
-
Compile all of your online help for your user-defined functions, user events, and user objects into a single file named PBUSR.CHM
-
Prefix the name of each user-defined function you create with uf_ (for example, uf_calculate)
Basic procedures
Here are details on how to build online help into the PowerBuilder environment.
To create context-sensitive help for user-defined functions:
-
When you create a user-defined function, give the name of the function a standard prefix. The default prefix is uf_ (for example, uf_calculate).
-
For each user-defined function help topic, assign a search keyword (a K footnote entry) identical to the function name.
For example, in the help topic for the user-defined function uf_CutBait, create a keyword footnote uf_CutBait. PowerBuilder uses the keyword to locate the correct topic to display in the help window.
-
Compile the help file and save it in the PowerBuilder Help directory.
You can specify a different file name for context-sensitive help:
To specify a different file name for context-sensitive help:
-
Open your PB.INI file in a text editor.
-
In the [PB] section, add a UserHelpFile variable, specifying the name of the help file that contains your context-sensitive topics. Your help file must be in the PowerBuilder Help directory. The format of the variable is:
UserHelpFile = helpfile.chm
Specify only the file name. A full path name designation will not be recognized.
You can change the prefix of your user-defined functions:
Two ways to call help from an application
PowerBuilder provides two principal ways of calling an online help file from a PowerBuilder application:
-
Use the ShowHelp and ShowPopupHelp PowerScript functions in your application scripts to call help topics.
-
Declare the HTML Help API as an external function and use the HTMLHelp function in your application scripts to call help topics.
Using ShowHelp
ShowHelp is simpler to implement than the HTML Help API. You can use the ShowHelp PowerScript function to search for help topics by help context ID, by keyword, and by accessing the help file Contents topic (the topic defined in the project file as the Help Contents topic). ShowHelp can also be used with compiled WinHelp (.hlp) files.
ShowPopupHelp displays pop-up help for a control. Typically, you use ShowPopupHelp in the Help event of a response window with the Context Help property enabled. Events relating to movement of the cursor over a control or to the dragging of a control or object are also logical places for a ShowPopupHelp call.
For more information on the ShowHelp and ShowPopupHelp functions as well as the Help event, see the section called “ShowHelp” in PowerScript Reference, the section called “ShowPopupHelp” in PowerScript Reference, the section called “Help” in PowerScript Reference.
Using the HTML Help API
Declaring and using the HTML Help API allows access to the full range of HTMLHelp functions, many of which are not available in ShowHelp. For example, using the HTMLHelp function, you can easily specify a window type or window name in which to present a help topic.
To declare the HTML Help API as an external function:
-
Select Declare>Global External Functions from the menu bar of any painter that accesses the Script view.
-
Enter the function declaration in the text box and click OK.
This example declares the HTML Help API:
FUNCTION long HtmlHelpW(long hWndMain, & string lpszHelp, long uCommand, & long dwData) & LIBRARY "hhctrl.ocx"
For more information about the HTML Help API, see the online help for the Microsoft Help Workshop or the documentation for your help authoring tool. For more information about declaring and using global external functions, see the section called “Declaring external functions” in PowerScript Reference and Using external functions.
