|
WSupported on Windows
|
|
|
|
status = %U_WINHELP([window_id], filename, command, data)
or
xcall U_WINHELP([window_id], filename, command, data)
Return value
status
On Windows, returns TRUE if successful or FALSE if unsuccessful. (^VAL)
On Unix and OpenVMS, always returns false.
Arguments
window_id
(optional) The ID of the window requesting Help. (n)
filename
The name of the Help file to invoke. The extension must be .hlp. (a)
command
The command code that specifies the type of help requested. See the Command Codes and Descriptions table for codes and descriptions. (n)
data
The specific data for the command code. (a or n)
Discussion
%U_WINHELP starts the Windows Help application (winhlp32.exe) and passes additional data indicating the nature of the help requested. The API is nearly identical to the Windows SDK “WinHelp” function, with two exceptions:
- Instead of passing a window handle, you pass a window ID which is translated to a handle. If you don’t pass window_id or if it is zero, the handle of the application window will be used.
- If you pass a numeric value in data, that value is passed directly to WinHelp. If you pass an alphanumeric value, %U_WINHELP copies and null-terminates data’s contents, and the address of the copied string is passed instead. This enables either alphanumeric strings or data structures to be passed in a native Synergy manner.
%U_WINHELP deactivates your application when it invokes WinHelp Help. Your application will remain suspended until reactivated, which will happen when either help is closed or the user returns to the application (by clicking on the application window with the mouse or by using Alt+Tab to switch back to the application).
If the user reactivates the application without closing Help, the Help will continue running (in a deactivated state) until %U_MSGBOX is called with the WHELP_QUIT command option or until the user closes Help. The user can keep Help displayed indefinitely while continuing to use the application.
%U_WINHELP uses window_id to keep track of which applications have requested Help.
You can display the help topic in a secondary window instead of the primary window by using the following syntax for filename:
filename>secondary_windowname
where secondary_windowname is the name of the window for displaying the topic. To use the secondary window specified, you must first define its name in the [WINDOWS] section of the Help project (.hpj) file.
The data value used depends on the value of the command argument. The following table shows the possible values for the command argument and the corresponding formats of data.
|
Data value |
Action |
|
|---|---|---|
|
WHELP_COMMAND |
Macro name (a) |
Executes a help macro. |
|
Zero (0) |
Displays Help for the topic specified by the CONTENTS setting in the .hpj file. |
|
|
WHELP_CONTEXT |
Context number for the topic (n) |
Displays Help for the topic identified by a context number that has been defined in the [MAP] section of the .hpj file. |
|
WHELP_CONTEXTPOPUP |
Context number for a topic (n) |
Displays Help in a pop-up window for the topic identified by a context number that has been defined in the [MAP] section of the .hpj file. |
|
WHELP_FORCEFILE |
Zero (0) |
Ensures that WinHelp is displaying the correct Help file. If the correct Help file is currently displayed, there is no action. If the incorrect Help file is displayed, WinHelp opens the correct file. |
|
WHELP_HELPONHELP |
Zero (0) |
Displays the Help Topics dialog box for Windows Help. |
|
WHELP_INDEX |
Zero (0) |
Displays the Help Contents topic. (See WHELP_CONTENTS.) |
|
WHELP_KEY |
Keyword (a) |
Displays the Index tab of the Help Topics dialog box with the specified keyword in the “Type the first few letters of the word you’re looking for” field. |
|
WHELP_MULTIKEY |
Multikey (a) |
Displays the structure identified by a keyword in an alternative keyword table. |
|
WHELP_PARTIALKEY |
Keyword (a) |
If there is one exact match, displays the topic found in the keyword list that matches the specified keyword. If there is more than one match, displays the Search dialog box with the topics listed in the Go To list box. If there is no match, displays the Search dialog box. To bring up the Search dialog box without passing a keyword (the third result), use a null string (“ ”). |
|
WHELP_QUIT |
Zero (0) |
Informs the Help application that Help is no longer needed. If no other applications have asked for Help, Windows closes the Help application. |
|
WHELP_SETCONTENTS |
Context number for the topic to be designated as the Index topic (n) |
Determines the Contents topic that Help is to display when a user presses the F1 key. |
|
WHELP_SETINDEX |
Context number for the topic (n) |
Specifies the Contents topic. |
|
WHELP_SETWINPOS |
Helpwininfo (a) (See below) |
Displays the Help structure, if it is minimized or in memory, and positions it according to the data passed. |
The multikey record definition must be defined as follows:
record multikey mksize ,i4 ;Length, in bytes, of this structure mkkeylist ,al ;Identifies the keyword table to search keyphase ,a* ;Contains the keyword to be located
The helpwininfo record definition must be defined as follows:
record helpwininfo ;Length, in bytes, structsize ,i4 ;of this structure x ,i4 ;Pixel x-coordinate of upper-left corner y ,i4 ;Pixel y-coordinate of upper-left corner dx ,i4 ;Width, in pixels dy ,i4 ;Height, in pixels wMax ,i4 ;Specifies how the window is to be shown rgchmember ,a* ;Unicode window name
