HelpHook

This hook processes help requests.

Syntax

HelpHook(hab, usMode, idTopic, idSubTopic, prcPosition);

Parameters

hab (HAB) - input

Anchor-block handle.

usMode (ULONG) - input

Help mode.

This has one of the following values, indicating the mode from which help has been requested:

HLPM_FRAME Standard (standard window)

HLPM_WINDOW Standard (standard window)

HLPM_MENU Menu mode

idTopic (ULONG) - input

Topic identifier.

In menu mode this is a pull-down window identity

In message-box mode this is the message-box identity

In standard mode this is a window identity.

idSubTopic (ULONG) - input

Subtopic identifier.

In menu mode this is a command identity

In message-box mode this is a control identity

In standard mode this is the identity of the window with the focus (-1 if none).

prcPosition (PRECTL) - input

Rectangle.

This indicates the screen area (in screen coordinates) from where the help was requested. It is provided to enable the help library to avoid covering that area.

In menu mode it is the bounding rectangle of the selected item, or o the top level menu if value of the idSubTopic parameter is -1.; In message-box mode it is the bounding rectangle of the button.; In standard mode it is the bounding rectangle of the window with the focus, or of the window sent the message if the value of the idSubTopic parameter is -1.
Note: The data type WRECT can also be used, if supported by the language.

Returns

rc (BOOL) - returns: Indicator as to whether next hook in the chain is called.; The message is always passed to the application.; TRUE: The next hook in the chain is not called.; FALSE: The next hook in the chain is called.

Remarks

Help-processing is done in two stages. The first stage is the creation of the WM_HELP message. This is done:

From a WM_CHAR message by ACCELERATOR table translation, when the HELP accelerator option is specified.
From an action-bar selection, when the MIS_HELP style is specified on the action-bar button.
From a dialog-box push button, when the BS_HELP style is specified on the push button.
From a message box, when the MB_HELP style is specified on the message box.

The WM_HELP message is sent to the active window, but will be seen by a modal loop if one is active.

The second stage of processing of help is the processing of the WM_HELP message.

The frame window procedure sees the WM_HELP message because the frame is usually the active window. It processes the WM_HELP message as follows:

If the window with the focus is the FID_CLIENT frame control, it passes WM_HELP to the FID_CLIENT window.
If the parent of the window with the focus is the FID_CLIENT frame control, it calls the help hook, specifying:

usMode = HLPM_WINDOW
idTopic = frame-window id
idSubTopic = focus-window id.

If the parent of the focus window is not the FID_CLIENT frame control (for example, it may be the frame itself, or a second-level dialog control), it calls the hook, specifying:

usMode = HLPM_WINDOW
idTopic = focus-window parent id
idSubTopic = focus-window id.

The message box window procedure sees the WM_HELP message, because it subclasses the frame window. It processes the WM_HELP message by calling the help hook, specifying:

usMode = HLPM_MESSAGE
idTopic = message id
idSubTopic = control id.

The menu window procedure sees the WM_HELP message because it runs a modal loop. It processes the WM_HELP message by calling the help hook, specifying:

usMode = HLPM_MENU
idTopic = menu id of pulldown
idSubTopic = menu id of item.

The WinDefWindowProc function sees the WM_HELP message for a FID_CLIENT window if the client does not handle it itself. It calls the help hook, specifying:

usMode = HLPM_WINDOW
idTopic = active-window id
idSubTopic = focus-window id.

An application sees the WM_HELP message in its dialog procedure. The application can ignore the WM_HELP message, in which case the frame-window procedure action occurs (as described above) or it can simulate a call to the help hook itself, using:

usMode = HLPM_APPLICATION
idTopic = any value
idSubTopic = any value.

The input focus is never given to any of the standard frame controls, so help for these cannot be obtained.

Related Messages

Example Code

#define INCL_WINHOOKS /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HAB     hab;        /* Anchor-block handle. */
ULONG   usMode;     /* Help mode. */
ULONG   idTopic;    /* Topic identifier. */
ULONG   idSubTopic; /* Subtopic identifier. */
PRECTL  prcPosition;/* Rectangle. */
BOOL    rc;         /* Indicator as to whether next hook in the chain is called. */

rc = HelpHook(hab, usMode, idTopic, idSubTopic,
       prcPosition);