IHelpHandler

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:

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:

true
The help event requires no additional processing. Do not pass it to another handler.
false
Pass the help event to the next handler for additional processing, as follows:
  • If there is another handler for the application frame window, pass the event to the next handler.
  • If this is the last handler for the application frame window, call IWindow::defaultProcedure to process the help event.


IHelpHandler - Member Functions and Data by Group

Constructors & Destructor

You can only construct IHelpHandler objects using its default constructor, which takes no parameters.


[view class]
~IHelpHandler
public:
virtual ~IHelpHandler()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IHelpHandler
public:
IHelpHandler()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

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.


[view class]
handleEventsFor
public:
virtual IHelpHandler& handleEventsFor( IFrameWindow* associatedWindow )

Attaches the handler to a frame window. The application frame window must be one of the following:

Exception

IInvalidParameter The associatedWindow must be nonzero.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stopHandlingEventsFor
public:
virtual IHelpHandler& stopHandlingEventsFor( IFrameWindow* associatedWindow )

Detaches the handler from the application frame window.

Exception

IInvalidParameter The associatedWindow must be nonzero.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dispatchHandlerEvent
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

A help handler contains event-processing members that you can use to provide application-specific processing for help-related events.


[view class]
controlSelect
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleError
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
helpUndefined
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:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hyperlinkSelect
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
keysHelpId
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
menuBarCommand
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
openLibrary
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showContents
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showCoverPage
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showHistory
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showIndex
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showPage
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showSearchList
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


[view class]
showTutorial
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.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
subitemNotFound
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
swapPage
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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

IPF/X does not generate an event for this condition.


IHelpHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data