### IFlyOverHelpHandler

  The IFlyOverHelpHandler class displays context-specific help for windows as the mouse moves over them. By attaching an IFlyOverHelpHandler to a window, you can provide context-specific help messages for that window and any of its descendent windows.

  You can use the IFlyOverHelpHandler to update an IFlyText control, an ITextControl, or both. Use the IFlyText control to display brief informative messages for a window, such as the function of a push button contained in a tool bar. Use ITextControl to display longer, more informative text like that found in an information area of a frame window. Typically, you will not have a string associated with every window in your application. When a help string cannot be found for a window, you can set "missing" text you would like displayed in the ITextControl. By default, a single blank is displayed in the ITextControl to avoid the frame extension handler from hiding the ITextControl when it contains a null string.
  Note: It is often convenient to use the same string table identifier for the text of a control and the text that is displayed in the IFlyText control. You can have the control text span multiple lines by having a new-line character in the string. While the new line is desirable for the control text, it is not desirable for the IFlyText control. For this reason, new-line characters are removed from a string before they are displayed in the IFlyText control.

  The last two parameters of each constructor specify time delays expressed in milliseconds. The first delay indicates an initial delay that the mouse must remain in the same location for the first time fly-over help is displayed for a window. The second delay indicates the time the mouse must remain in the same location after the first time fly-over help has been displayed. For example, the first time fly-over help is displayed, you may want to set the initial delay to two seconds. Then, you may want to set the second delay to one-half second.

  The primary method of associating context-specific help for a window to a help message is by a window identifier, as is the case for IInfoArea. The window identifier, in conjunction with an offset that is added to the window identifier, is used to load strings from a string table. You can specify different offsets into the string table for the IFlyText and the ITextControl objects, thereby allowing you to display different help messages for a window in each of the controls.
  Note: To display help for a window via a string table in a resource file based on the windows identifier, you must either create the window via the User Interface Class Library or wrapper an existing window.

  In addition to loading help text via a string table in a resource file, you can also dynamically associate help text to a window. This association is made using window handles. This is useful if you dynamically add controls to a canvas or push buttons to a tool bar. If you dynamically add help text to a window, this takes precedence over help that is otherwise loaded from a string table.

  Fly-Over Help

### IFlyOverHelpHandler - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.
Note: Each constructor's last two parameters are optional. These parameters are delay times expressed in milliseconds. The first delay indicates an initial delay that the mouse must remain in the same location for the first time fly-over help is displayed for a window. The second delay indicates the time the mouse must remain in the same location after the first time fly-over help has been displayed.

~IFlyOverHelpHandler

      public:
      virtual ~IFlyOverHelpHandler()

Supported Platforms

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

IFlyOverHelpHandler

  Overload 1

      public:
      IFlyOverHelpHandler( ITextControl* longText,
                           unsigned long initialDelay = 100,
                           unsigned long delay = 100 )

  Use this function to construct objects of the IFlyOverHelpHandler class from a ITextControl object. Typically, you display longer, more informative help messages for the window the mouse is over.

Supported Platforms

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

  Overload 2

      public:
      IFlyOverHelpHandler( IFlyText* flyText,
                           ITextControl* longText,
                           unsigned long initialDelay = 100,
                           unsigned long delay = 100 )

  Use this function to construct an object of the IFlyOverHelpHandler class from a IFlyText object and a ITextControl object.

Supported Platforms

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

  Overload 3

      public:
      IFlyOverHelpHandler( IFlyText* flyText,
                           unsigned long initialDelay = 100,
                           unsigned long delay = 100 )

  Use this function to construct objects of the IFlyOverHelpHandler class from a IFlyText object and optionally an initial delay and delay time in milliseconds. Use the IFlyText control to display brief help messages.

Supported Platforms

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

### Dynamically Updating Help Text

These members dynamically add help text to or remove it from a window. If you add help text to a window by the setHelpText functions, this text takes precedence over text that would otherwise be loaded from a string table.

flyHelpText

      public:
      virtual IString
        flyHelpText( const IWindowHandle& handle ) const

  Returns the short help text for a window if you have dynamically added help text for the window.

Supported Platforms

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

longHelpText

      public:
      virtual IString
        longHelpText( const IWindowHandle& handle ) const

  Returns the long help text for a window if you have dynamically added long help text for the window.

Supported Platforms

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

removeHelpText

      public:
      virtual IFlyOverHelpHandler&
        removeHelpText( const IWindowHandle& handle )

  Removes help text added to a window using setHelpText.

Supported Platforms

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

setHelpText

  Sets the help text for a window by specifying a string or resource identifier.

  Overload 1

      public:
      virtual IFlyOverHelpHandler&
        setHelpText( const IWindowHandle& handle,
                     const IString& flyText,
                     const IString& longText = IString ( ) )

Supported Platforms

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

  Overload 2

      public:
      virtual IFlyOverHelpHandler&
        setHelpText( const IWindowHandle& handle,
                     const IResourceId& flyText,
                     const IResourceId& longText )

Supported Platforms

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

### Event Dispatching

Event-dispatching members evaluate an event to determine if it is appropriate for this handler object to process.

handleEventsFor

      public:
      virtual IFlyOverHelpHandler&
        handleEventsFor( IWindow* window )

  Attaches the handler to the specified window passed in the argument.

Supported Platforms

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

stopHandlingEventsFor

      public:
      virtual IFlyOverHelpHandler&
        stopHandlingEventsFor( IWindow* window )

  Detaches the handler from the specified window passed in the argument.

Supported Platforms

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

dispatchHandlerEvent

      protected:
      virtual bool dispatchHandlerEvent(IEvent& event)

  This function intercepts events that are necessary to determine which window the mouse is over.

Supported Platforms

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

### Querying and Setting Text Controls

Use these members to query and set the text controls that display help text.

flyTextControl

      public:
      virtual IFlyText* flyTextControl() const

  Returns a pointer to the fly text control that is used to display fly help text.

Supported Platforms

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

longTextControl

      public:
      virtual ITextControl* longTextControl() const

  Returns a pointer to the text control that is used to display long help text.

Supported Platforms

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

setFlyTextControl

      public:
      virtual IFlyOverHelpHandler&
        setFlyTextControl( IFlyText* flyText )

  Sets the control to use to display fly help text.

Supported Platforms

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

setLongTextControl

      public:
      virtual IFlyOverHelpHandler&
        setLongTextControl( ITextControl* longText )

  Sets the control to use to display long help text.

Supported Platforms

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

### Resource Library

Use these members to query and set the resource library from which the information strings are loaded.

resourceLibrary

      public:
      virtual IResourceLibrary& resourceLibrary() const

  Returns a reference to the library being used.

Supported Platforms

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

setResourceLibrary

  Sets the resource library to be used. This can be specified as a .dll file, or a library name, with an optional search path.

  Overload 1

      public:
      virtual IFlyOverHelpHandler&
        setResourceLibrary( const char* resDLLName )

Supported Platforms

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

  Overload 2

      public:
      virtual IFlyOverHelpHandler&
        setResourceLibrary( const IModuleHandle& resMod )

Supported Platforms

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

### Special Information Strings

Use these members to query and set the value of the information strings displayed in special circumstances. Special circumstances include when the information string is not found for the ITextControl. You can specify each special string as either an IString or the identifier for a string from the resource library.

defaultText

      public:
      virtual IString defaultText() const

  Returns the text to display when an information string is not found for the ITextControl.

Supported Platforms

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

setDefaultText

  Sets the text to display when an information string is not found for the ITextControl.

  Overload 1

      public:
      virtual IFlyOverHelpHandler&
        setDefaultText( const IString& defaultText )

Supported Platforms

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

  Overload 2

      public:
      virtual IFlyOverHelpHandler&
        setDefaultText( unsigned long identifier )

Supported Platforms

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

### String Table Offset

Use these members to query and set a string table offset. This offset added to the window identifier for the window that the mouse is over is used to compute a value. The value is used to obtain a string from a string table. The default offset is 0.

flyTextStringTableOffset

      public:
      virtual long flyTextStringTableOffset() const

  Returns the offset currently in use for the fly text control.

Supported Platforms

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

longStringTableOffset

      public:
      virtual long longStringTableOffset() const

  Returns the offset currently in use for the long text control.

Supported Platforms

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

setFlyTextStringTableOffset

      public:
      virtual IFlyOverHelpHandler&
        setFlyTextStringTableOffset( long newOffset = 0 )

  Sets the offset to be used to calculate the information string identifier for the text displayed in the fly text control.

Supported Platforms

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

setLongStringTableOffset

      public:
      virtual IFlyOverHelpHandler&
        setLongStringTableOffset( long newOffset = 0 )

  Sets the offset to be used to calculate the information string identifier for the text displayed in the long text control.

Supported Platforms

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

### Timer Delay

Use these members to query and set a timer delay. This timer delay specifies the time that the mouse must remain in the same location before help is displayed for the window under the mouse.

delayTime

      public:
      virtual unsigned long delayTime() const

  Returns the minimum time, in milliseconds, the mouse must remain in the same position before help text is displayed.

Supported Platforms

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

initialDelayTime

      public:
      virtual unsigned long initialDelayTime() const

  Returns the minimum time, in milliseconds, the mouse must remain in the same location for the first time fly over help is displayed for a window.

Supported Platforms

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

setDelayTime

      public:
      virtual IFlyOverHelpHandler&
        setDelayTime( unsigned long milliseconds = 100 )

  Specifies the minimum time, in milliseconds, that the mouse must remain in the same position before help text is displayed.

Supported Platforms

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

setInitialDelayTime

      public:
      virtual IFlyOverHelpHandler&
        setInitialDelayTime( unsigned long milliseconds = 100 )

  Sets the minimum time, in milliseconds, the mouse must remain in the same location for the first time fly over help is displayed for a window.

Supported Platforms

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

### Miscellaneous Members

setResourceLibrary

      public:
      virtual IFlyOverHelpHandler&
        setResourceLibrary( const char* resDLLName,
                            IDynamicLinkLibrary::ESearchLocation searchLocation = IDynamicLinkLibrary::kOSDefaultSearch )

  Sets the resource library to be used. This can be specified as a .dll file, or a library name, with an optional search path.

Supported Platforms

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

### IFlyOverHelpHandler - 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)

  -     virtual IHandler& handleEventsFor(IWindow* window)

  -     IHandler()

  -     bool isEnabled() const

  -     virtual IHandler& stopHandlingEventsFor(IWindow* window)

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None