%U_WINHELP

Invoke WinHelp Help

WSupported on Windows

 

 

 

status = %U_WINHELP([window_id], filename, command, data)

or

xcall U_WINHELP([window_id], filename, command, data)

status

On Windows, returns TRUE if successful or FALSE if unsuccessful. (^VAL)

On Unix and OpenVMS, always returns false.

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)

%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:

%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.

Command Codes and Descriptions

Command

Data value

Action

WHELP_COMMAND

Macro name (a)

Executes a help macro.

WHELP_CONTENTS

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)
(see below)

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