The IHelpHandler class processes events related to a help window. While you can provide help support without using the IHelpHandler class, and can provide basic error support without deriving from IHelpHandler, you need to create a class derived from IHelpHandler to provide more advanced help support.
You attach a help handler object to an application frame window by calling IHelpHandler::handleEventsFor, passing the window to the help handler. Only attach help handlers to frame windows that you have associated with a help window, either when constructing an IHelpWindow object or when calling IHelpWindow::setAssociatedWindow.
A help handler allows you to process the following help events:
You can process this request by overriding the function keysHelpId.
You can dynamically display a contextual help panel for such a control by overriding the function subitemNotFound.
You can process this request by overriding the function helpUndefined.
To process, override the function showCoverPage.
To process, override the function showPage.
To process, override the function swapPage.
To process, override the function showContents.
To process, override the function showHistory.
To process, override the function showIndex.
To process, override the function showSearchList.
To process, override the function openLibrary.
To process, override the function controlSelect.
When the help handler receives one of these help events, it creates a corresponding event object and routes that object to the appropriate IHelpHandler virtual function. Override these virtual functions to supply your own specialized processing of these events.
The return value from the virtual functions specifies whether the event is passed on for additional processing, as follows:
You can only construct IHelpHandler objects using its default constructor, which takes no parameters.
![]() |
public:
virtual ~IHelpHandler()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IHelpHandler()
Windows | OS/2 | AIX |
Yes | Yes | Yes |
The Open Class Library dispatches events that have been sent or posted to a window to each of the handlers attached to that window. It does this by calling the event-dispatching function of each handler object.
An IHelpHandler object processes only help-related events and can only be attached to and detached from a frame window.
![]() |
public:
virtual IHelpHandler& handleEventsFor( IFrameWindow* associatedWindow )
Attaches the handler to a frame window. The application frame window must be one of the following:
IInvalidParameter | The associatedWindow must be nonzero. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual IHelpHandler& stopHandlingEventsFor( IFrameWindow* associatedWindow )
Detaches the handler from the application frame window.
IInvalidParameter | The associatedWindow must be nonzero. |
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool dispatchHandlerEvent(IEvent& event)
If this handler receives a help event, this function creates the appropriate type of help event object and calls the appropriate virtual function to process it.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
A help handler contains event-processing members that you can use to provide application-specific processing for help-related events.
![]() |
protected:
virtual bool controlSelect(IHelpNotifyEvent& event)
Called when the user selects an application-added control on a help window. By default, this function does nothing and returns false.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool handleError(IHelpErrorEvent& event)
Called when a help-related error occurs. By default, this function displays a message box indicating the error type of the IHelpErrorEvent. The error type is an enumerator provided by ErrorType.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool helpUndefined(IEvent& event)
Called when the user requests general help and it is not defined. By default, this function does nothing, setting the event result to false. Your application can override this function and do either of the following:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool hyperlinkSelect(IHelpHyperlinkEvent& event)
Called when the user refers to a heading that contains an inform link. This informs the application that the heading is accessed. You specify this link using the reftype=inform attribute on the Information Presentation Facility (IPF) link tag. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool keysHelpId(IEvent& event)
Called when the user selects the Keys Help choice from a help window or from a menu. By default, this function sets the event result to 0, indicating that no panel is to be displayed. You can override the default action by setting the event result to the ID of the help panel that you want IPF to display as the keys help panel.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool menuBarCommand(IHelpMenuBarEvent& event)
Called when the user selects an application-added item on a customized menu bar used by the help window. By default, this function does nothing, setting the event result to false.
Use the function IHelpWindow::Settings::setMenuBar to assign a custom menu bar to the help window.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool openLibrary(IHelpNotifyEvent& event)
Called when the Libraries list window is about to be displayed. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showContents(IHelpNotifyEvent& event)
Called when the help Contents window is about to be displayed. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showCoverPage(IHelpNotifyEvent& event)
Called when the help cover page window is about to be displayed. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showHistory(IHelpNotifyEvent& event)
Called when the Viewed Pages window is about to be displayed. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showIndex(IHelpNotifyEvent& event)
Called when the help Index window is about to be displayed. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showPage(IHelpNotifyEvent& event)
Called when a child window of the cover page is about to be opened. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showSearchList(IHelpNotifyEvent& event)
Called when the search list window is about to be displayed. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
![]() |
protected:
virtual bool showTutorial(IHelpTutorialEvent& event)
Called when the user selects the Tutorial choice from a help window or from a menu. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Ignored | Yes | Ignored |
![]() |
protected:
virtual bool subitemNotFound( IHelpSubitemNotFoundEvent& event )
Called when the user requests help on a control or window that cannot be found in the help table that is currently in use for the IHelpWindow object. By default, this function does nothing but return false, resulting in extended help being shown.
You can provide your own functionality for this event by overriding this function. To prevent extended help from being shown, set the event result to true using IEvent::setResult on the IHelpSubitemNotFoundEvent object passed into the function.
Returning true from the function itself will prevent other handlers from processing this event.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
protected:
virtual bool swapPage(IHelpNotifyEvent& event)
Called when a child window of the cover page is about to be swapped. By default, this function does nothing, setting the event result to false.
Windows | OS/2 | AIX |
Yes | Yes | Ignored |
IPF/X does not generate an event for this condition.
virtual IEventResult defaultProcedure(IEvent& event)
virtual bool dispatchHandlerEvent(IEvent& event) = 0