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.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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


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


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


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


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


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


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


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


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


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


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


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


[view class]
resourceLibrary
public:
virtual IResourceLibrary& resourceLibrary() const

Returns a reference to the library being used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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


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


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


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


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


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


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


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


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


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


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


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

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data