IHelpWindow

The IHelpWindow class provides help for application windows that use Information Presentation Facility (IPF) and for native help on the Windows platform. Typically, you create an IHelpWindow object and associate it with the primary windows of your application. Multiple IPF help windows can also exist within an application. When an application window is associated with a help window, help events are dispatched to the help handler attached to the associated application window.

Portability Considerations

The class default style for the IHelpWindow class is different in the Windows environment. In the OS/2 and AIX environments, the default is set to IHelpWindow::ipfCompatible and cannot be changed. In the Windows environment, the default is set for native Windows help. You can change the default to IHelpWindow::ipfCompatible style by calling IHelpWindow::setDefaultStyle.

When using the native Windows help, many of the IHelpWindow methods, for example IHelpWindow::hidePanelIds, perform no other function than to return a reference to the IHelpWindow object or null. Also, because native Windows help does not send messages back to the application, most of the IHelpHandler functions are never called. For more details, see the function descriptions for the IHelpWindow and IHelpHandler classes.

AIX Considerations

You can build the viewable help files for your AIX application using the Information Presentation Facility compiler (IPFC) that comes with the Developer's Toolkit for OS/2, version 2.1 or later.

Instead of compiling an IPF file using code page 437, as you would to view help on the OS/2 platform, you must compile the file on the OS/2 platform using code page 850 to view the help on AIX.

IHelpWindow uses the window identifier of the IWindow object as the identifier of the contextual or general help panel to display.

Windows Considerations

By default, IHelpWindow objects constructed in the Windows environment use native Windows help. To prepare your program to use this style of help, you build a .hlp file using the Windows help compiler from a source file written in Rich Text Format (RTF) and then access the help file using the portable IHelpWindow classes. This approach gives you the ability to port your application code while providing your users with native look-and-feel when using help. However, you should note the following differences in IHelpWindow behavior.

If you prefer to show help using IPF on Windows, set the default IHelpWindow style before constructing the IHelpWindow object. You do this using the static IHelpWindow function:

IHelpWindow::setDefaultStyle(IHelpWindow::ipfCompatible);

You can also set the help window style by specifying the appropriate style on the IHelpWindow constructor.


IHelpWindow - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IHelpWindow objects because both the copy constructor and assignment operator are private functions.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IHelpWindow


Overload 1
public:
IHelpWindow( const IResourceId& helpTable, IFrameWindow* associatedWindow, const IHelpWindow::Style& style = defaultStyle ( ) )
helpTable
Resource identifier for a help table resource.
associatedWindow
Frame window to be associated with the help window.

For you to provide an application window with contextual or general help using help tables, the window must be an associated window, have an associated window in its parent window chain, or be a secondary window owned by an associated window. IPF also sends help notification events to associated frame windows, positions the help window to minimally overlap an associated frame window, closes the help window when the associated frame window is closed, and activates the associated frame window when the user dismisses the help window.

style
Type of help window to construct. If you do not specify style, the constructor calls IHelpWindow::defaultStyle to return the default style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IHelpWindow( IFrameWindow* associatedWindow = 0, const IHelpWindow::Style& style = defaultStyle ( ) )
associatedWindow
Frame window to be associated with the help window.

For you to provide an application window with contextual or general help using help tables, the window must be an associated window, have an associated window in its parent window chain, or be a secondary window owned by an associated window. IPF also sends help notification events to associated frame windows, positions the help window to minimally overlap an associated frame window, closes the help window when the associated frame window is closed, and activates the associated frame window when the user dismisses the help window.

If you do not specify an application frame window to be associated with the help window object, you can later call the function IHelpWindow::setAssociatedWindow to make this association.

style
Type of help window to construct. If you do not specify style, the constructor calls IHelpWindow::defaultStyle to return the default style.

Exception

IAccessError Information Presentation Facility (IPF) could not create the help window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IHelpWindow( const Settings& settings, IFrameWindow* associatedWindow = 0, const IHelpWindow::Style& style = defaultStyle ( ) )
settings
An object of the class IHelpWindow::Settings to associate the help window with initial information, such as the following:
  • Customized menu bar
  • Accelerator table
  • Title text
  • Tutorial program
  • Help panel libraries
associatedWindow
Frame window to be associated with the help window.

For you to provide an application window with contextual or general help using help tables, the window must be an associated window, have an associated window in its parent window chain, or be a secondary window owned by an associated window. IPF also sends help notification events to associated frame windows, positions the help window to minimally overlap an associated frame window, closes the help window when the associated frame window is closed, and activates the associated frame window when the user dismisses the help window.

You can also call the function IHelpWindow::setAssociatedWindow to associate a frame window with the IHelpWindow object.

style
Type of help window to construct. If you do not specify style, the constructor calls IHelpWindow::defaultStyle to return the default style.

This is the most flexible IHelpWindow constructor because the IHelpWindow::Settings class allows you to specify a wide amount of information, including a tutorial, menu bar, and accelerator table, for which the IHelpWindow class does not provide member functions.

Exception

IAccessError Information Presentation Facility (IPF) could not create the help window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations
See IHelpWindow::Settings Windows notes for a description of which settings are supported in the Windows environment.


Overload 4
public:
IHelpWindow(const IWindowHandle& helpWindowHandle)
helpWindowHandle
Window handle of an existing help window.

Only this constructor allows you to create an IHelpWindow object for an existing help window. All other constructors create a help window.

Exception

IInvalidParameter helpWindowHandle is 0. It must be a valid window handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Application Windows

You can use the same IHelpWindow object to service help requests for many application windows created in the same thread, regardless of whether they are primary, secondary, or child frame windows. You can control the help subtable that IPF uses to display contextual help by managing the active window, control where IPF positions a help panel by managing the relative window, and control the owner window of a help panel by managing the associated window.


[view class]
setActiveWindow
public:
virtual IHelpWindow& setActiveWindow( IFrameWindow* activeWindow, IFrameWindow* relativeWindow = 0 )

Sets the application window from which IPF expects subsequent requests for contextual or general help. With this function, you can enable IPF to display contextual and general help panels for a child frame window using help tables and subtables. For this case, IPF would otherwise treat the parent frame window as the active window.

Optionally, you can specify the window to position the help window next to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), you can still use this function to control which help subtable to use when displaying contextual or general help. However, since there is only one native Windows help instance per system, the help window is not positioned relative to your application's window. Therefore, for native Windows help, setting the second parameter will have no effect.


[view class]
setAssociatedWindow
public:
virtual IHelpWindow& setAssociatedWindow( IFrameWindow* associatedWindow )

Associates an application frame window with the help window. More than one window can be associated with a help window.

For you to provide an application window with contextual or general help using help tables, the window must be an associated window, have an associated window in its parent window chain, or be a secondary window owned by an associated window. IPF also sends help notification events to associated frame windows, positions the help window to minimally overlap an associated frame window, closes the help window when the associated frame window is closed, and activates the associated frame window when the user dismisses the help window.

This function allows you to use the same help window for multiple primary windows. Additionally, you can better manage help windows for a secondary frame window. This might be necessary if a primary window would otherwise be the associated window. By making a secondary frame window the associated window you get these results:

A frame window is automatically disassociated from a help window when it closes.

Exception

IInvalidParameter associatedWindow is 0. It must be a valid window handle.
IAccessError Information Presentation Facility (IPF) could not associate the specified window with the help window. Possibly associatedWindow does not represent a valid window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Help Panels

Most of the help information that a user sees is typically in the form of help panels.You can direct IPF to display help panels for contextual and general help based on a help table. You can also show specialized help panels or help windows programmatically, independent of help tables.


[view class]
addLibraries
public:
virtual IHelpWindow& addLibraries( const char* helpLibraryNames )

Adds a library or list of libraries to those already used by IPF. IPF searches these help libraries for the help panels that it displays. This function deals with binary help files that have an .hlp extension.

Exception

IInvalidRequest Information Presentation Facility (IPF) is unable to add the specified help libraries. Possibly it could not open the help library files.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

If you want to use the HELP Setting to search for the help library files, specify the file names without a directory or path.

Windows Considerations

When using the native Windows help style for IHelpWindow objects, you should only pass a single file name on the addLibraries call. The filename should identify the help file that was compiled with the Windows help compiler from a Rich Text Format (RTF) source file.


[view class]
hide
public:
virtual IHelpWindow& hide()

Closes the help window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setHelpTable
public:
virtual IHelpWindow& setHelpTable( const IResourceId& helpTable )

Sets the help table for IPF to use for satisfying user requests for contextual and general help. Entries in the help table identify the help panel to be searched for in the help libraries, for a given application frame window or control.

This function replaces any help table identified with the class IHelpWindow::Settings.

You can also associate help panels with IWindow or IMenu item objects directly by calling IWindow::setHelpId or IMenu::setItemHelpId.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setUsingHelp
public:
virtual IHelpWindow& setUsingHelp(unsigned long panelId)

Sets the help panel to use instead of the default Using Help panel provided by IPF. Calling IHelpWindow::show and specifying IHelpWindow::usingHelp causes IPF to show this help panel.

This function replaces any Using Help panel identified with the class IHelpWindow::Settings.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function will change the help panel that is displayed when calling IHelpWindow::show with the HelpType of usingHelp.


[view class]
show

Displays a help panel or specialized help window.


Overload 1
public:
virtual IHelpWindow& show(HelpType helpType)
helpType
Enumerator value from the HelpType enumeration.

The enumerator identifies a help panel or kind of help window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), the HelpType enumeration values have different meanings.


Overload 2
public:
virtual IHelpWindow& show(const IResourceId& panelId)
panelId
Resource identifier for the help panel from your help (.hlp) file that you want to show.

If you specify an identifier of 0, the Using Help window is displayed.
Note: The IResourceLibrary portion of the panelId value is ignored.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IHelpWindow& show(const char* panelName)
panelName
The name of the help panel.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function calls Windows help, using the panel name as a keyword.


Panel Identifiers

You can uniquely identify a help panel by its help panel identifier. You can have help panels display their panel IDs for diagnostic purposes.


[view class]
hidePanelIds
public:
virtual IHelpWindow& hidePanelIds()

Removes the identifier for a help panel from its title bar text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


[view class]
showPanelIds
public:
virtual IHelpWindow& showPanelIds(bool visibleId = true)

Adds the identifier for a help panel to its title bar text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


Sending and Posting Events

Event send and post members are overridden to ensure events get routed to the correct window.


[view class]
sendEvent

Sends the specified event to the help window.


Overload 1
public:
virtual IEventResult sendEvent(const IEvent& event) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IEventResult sendEvent( unsigned long eventId, const IEventParameter1& parm1 = 0, const IEventParameter2& parm2 = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IEventResult sendEvent( EventType eventType, const IEventParameter1& parm1 = 0, const IEventParameter2& parm2 = 0 ) const

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

IHelpWindow defines objects of the nested class IHelpWindow::Style. You can use these styles with IHelpWindow::setDefaultStyle.


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. This style is equivalent to IHelpWindow::classDefaultStyle unless you have changed the style using IHelpWindow::setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isIPFCompatible
public:
bool isIPFCompatible() const

Returns true if the IPF is being used to display application help information. True is always returned, except on Windows where true means IPF is being used and false means that native Windows help is being used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for construction of all subsequent help windows. You only need this function in the Windows environment and then only if you want to change which help manager you want to use to process application help requests.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

To change from native Windows help to IPF help, use:

setDefaultStyle(IHelpWindow::ipfCompatible).

To change from IPF help to native Windows help, use:
setDefaultStyle(~IHelpWindow::ipfCompatible).

[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IHelpWindow::ipfCompatible, except on Windows where it is set to IHelpWindow::noStyle, meaning native Windows help.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ipfCompatible
public:
static const Style ipfCompatible

Specifies that IHelpWindow should use IPF to display application help information. Except for the Windows environment, this style is always on. For Windows, the default is IHelpWindow::noStyle, therefore native Windows help is used. To use IPF on Windows, call IHelpWindow::setDefaultStyle with this style before constructing your IHelpWindow object or specify this style on the IHelpWindow constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noStyle
public:
static const Style noStyle

You use this style in the Windows environment to specify that native Windows help should be used to show help information. You only need to use this style if you have previously changed the default style to ipfCompatible. You change your default IHelpWindow style by calling, IHelpWindow::setDefaultStyle.

In all other environments, using this style has no effect.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Title Text

The IHelpWindow class allows you to control the text displayed in the title bar of the cover page window.


[view class]
setTitle

Sets the title bar text for the help window.

These functions replace any title identified with the class IHelpWindow::Settings.


Overload 1
public:
virtual IHelpWindow& setTitle(const IResourceId& titleId)
titleId
Resource identifier of a string in a string table.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


Overload 2
public:
virtual IHelpWindow& setTitle(const char* titleText)
titleText
Address of a character string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


Window Accessing

Many different help-related windows can be displayed during the course of an application. You can access the different types of windows to provide application-specific processing or customization.


[view class]
communicationWindow
public:
IWindowHandle communicationWindow() const

Returns the handle of the active communication window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


[view class]
contentsWindow
public:
IWindowHandle contentsWindow() const

Returns the handle of the Table of Contents window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


[view class]
coverPageWindow
public:
IWindowHandle coverPageWindow() const

Returns the handle of the IPF multiple-document-interface parent window. This is the window within which all other IPF windows are displayed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


[view class]
handle
public:
virtual IWindowHandle handle() const

Returns the handle of the help window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), a unique window handle is returned, butsince native Windows help provides only one help instance per system, the handle provides no other purpose than unique identification.


[view class]
helpWindow
public:
static IHelpWindow* helpWindow(const IWindow* window)

Returns the help window that is associated with the specified application window. The parent window chain is searched until an application window associated with a help window is found, in which case this function returns that help window. If a help window cannot be found, 0 is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
indexWindow
public:
IWindowHandle indexWindow() const

Returns the handle of the Index window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


[view class]
searchListWindow
public:
IWindowHandle searchListWindow() const

Returns the handle of the Search window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


[view class]
viewedPagesWindow
public:
IWindowHandle viewedPagesWindow() const

Returns the handle of the Viewed Pages window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect.


Window Positioning

The IHelpWindow class allows you to size and position the cover page window, within which all other IPF windows are displayed.


[view class]
moveSizeTo
public:
virtual IHelpWindow& moveSizeTo( const IRectangle& rectangle )

Changes the size and position of the help cover page window, within which all other IPF windows are displayed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function will move and size the single system instance of native Windows help.


[view class]
moveTo
public:
virtual IHelpWindow& moveTo(const IPoint& point)

Changes the position of the help cover page window, within which all other IPF windows are displayed. Call this function only when the help window is visible.

Exception

IInvalidRequest The help window is not visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect. You can use IHelpWindow::moveSizeTo to change both the size and position of the single native Windows help instance.


[view class]
sizeTo
public:
virtual IHelpWindow& sizeTo(const ISize& size)

Changes the size of the help cover page window, within which all other IPF windows are displayed. Call this function only when the help window is visible.

Exception

IInvalidRequest The help window is not visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help (that is, you did not construct your IHelpWindow object with the IHelpWindow::ipfCompatible style), this function has no effect. You can use IHelpWindow::moveSizeTo to change both the size and position of the single native Windows help instance.


IHelpWindow - Enumerations


[view class]
HelpType
enum HelpType { index, 
                general, 
                contents, 
                keys, 
                usingHelp, 
                using=usingHelp }

Use these enumerators to identify a type of help window or help panel:

index
The help Index window.
general
The general help panel for the current frame window.
contents
The help file Table of Contents window.
keys
The keys help panel.
usingHelp
The Using Help panel.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

If you are using native Windows help, HelpType values have the following meanings:

index
The Windows help Finder window that displays an index and provides searching capability.
general
The general help panel for the current frame window.
contents
The help file Table of Contents window.
keys
The keys help panel.
usingHelp
The Windows help Help on Help window.


IHelpWindow - Inherited Member Functions and Data

Inherited Public Functions

INotifier
IWindow

Inherited Public Data

IWindow
INotifier

Inherited Protected Functions

IWindow
INotifier

Inherited Protected Data