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

  - Requests for help when the following occurs:
    - The user selects the Keys Help menu choice.

      You can process this request by overriding the function keysHelpId.

    - The active control has no contextual help panel defined in the help table resource.

      You can dynamically display a contextual help panel for such a control by overriding the function subitemNotFound.

    - The active frame window has no general help defined.

      You can process this request by overriding the function helpUndefined.

  - Errors related to help processing. You can process these errors by overriding the function handleError.
  - Selection of the Tutorial menu choice. You can process this action by overriding the function showTutorial.
  - Notification of the following:
    - The help cover page window is about to be shown.

      To process, override the function showCoverPage.

    - A page within the cover page window is about to be shown.

      To process, override the function showPage.

    - A page is about to be swapped.

      To process, override the function swapPage.

    - The help Contents window is about to be shown.

      To process, override the function showContents.

    - The Viewed Pages window is about to be shown.

      To process, override the function showHistory.

    - The help Index window is about to be shown.

      To process, override the function showIndex.

    - The search list window is about to be shown.

      To process, override the function showSearchList.

    - The Libraries list window is about to be shown.

      To process, override the function openLibrary.

    - The user selected an application-added control on a help window.

      To process, override the function controlSelect.

  - Selection of an application-added item on a customized help menu bar. You can process this action by overriding the function menuBarCommand.
  - Selection of a special link on a help panel. You can process this action by overriding the function hyperlinkSelect.

  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.

~IHelpHandler

      public:
      virtual ~IHelpHandler()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

handleEventsFor

      public:
      virtual IHelpHandler&
        handleEventsFor( IFrameWindow* associatedWindow )

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

  - The window you specified when constructing an IHelpWindow object (this is typically a primary window)
  - A window you specified when calling the function IHelpWindow::setAssociatedWindow

Exception

  IInvalidParameter | The associatedWindow must be nonzero.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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.

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

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

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:

  - Display its own help panel
  - Use IHelpWindow::show to display a particular help panel or window.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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

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

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

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.

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.

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.

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.

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.

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.

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.

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

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

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

  -     virtual ~IHandler()

  -     virtual IString asDebugInfo() const

  -     virtual IString asString() const

  -     virtual IHandler& disable()

  -     virtual IHandler& enable(bool enable = true)

  -     IHandler()

  -     bool isEnabled() const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None