NAME

XmtHelpDoContextHelp(), XmtHelpDisplayContextHelp(), XmtHelpGetContextHelp() - context help functions.

SYNOPSIS

#include <Xmt/Help.h>

void XmtHelpDoContextHelp(Widget w)

void XmtHelpDisplayContextHelp(Widget w)

void XmtHelpGetContextHelp(Widget w, String *help_return, String *title_return)

ARGUMENTS

INPUTS

w: For XmtHelpDoContextHelp(), any widget in the application. For XmtHelpDisplayContextHelp() and XmtHelpGetContextHelp(), the widget for which help is to be displayed or obtained.

OUTPUTS

help_return: For XmtHelpGetContextHelp(), returns the context help associated with w, or NULL if none is found. The string returned at this address should be freed with XtFree() when no longer needed.
title_return: For XmtHelpGetContextHelp(), returns the title of the context help associated with w, or NULL if none is found. The string returned at this address should be freed with XtFree() when no longer needed.

DESCRIPTION

Context help may be associated with any widget in an application by setting the xmtHelp and xmtHelpTitle pseudo-resources, as described in Chapter 30, Context Help. The three functions XmtHelpDoContextHelp(), XmtHelpDisplayContextHelp(), and XmtHelpGetContextHelp() are interfaces to the context help mechanism at three different levels of abstraction.

XmtHelpDoContextHelp() calls the Motif function XmTrackingLocate() which displays a special cursor, waits until the user clicks the mouse button, and returns the widget that was clicked on. Once a widget is selected, XmtHelpDoContextHelp() calls XmtHelpDisplayContextHelp() to display context help for that specified widget in a dialog box. If no widget was selected, XmtHelpDoContextHelp() sounds the bell to indi cate an error.

XmtHelpDoContextHelp() prompts the user with a cursor specified by the helpCursor application resource. The default value of this resource is the ``question_arrow'' cursor in the standard X11 cursor font.

XmtHelpDisplayContextHelp() calls XmtHelpGetContextHelp() to look up the context help for the widget w, and then displays the returned help text and title string in an automatically created and cached modeless XmtHelpBox dialog.

If there is no context help text defined for the specified widget, XmtHelpDisplayContextHelp() displays the string ``There is no help available there''. If no help title is defined, it displays the title ``Context Help''. The pixmap displayed in the XmtHelpBox dialog can be specified with the XmtNcontextHelpPixmap application resource. The default pixmap is an enlarged version of the ``question_arrow'' cursor used as the default context help cursor by XmtHelpDoContextHelp().

The dialog boxes displayed by XmtHelpDisplayContextHelp() (and indirectly by XmtHelpDoContextHelp()) are not created until they are needed, and are cached for reuse. They are modeless so that the use may keep them displayed for as long as desired and may dismiss them at any time. These dialogs are completely managed by Xmt; you need not, and should not, take any action to destroy or unmanage them.

XmtHelpGetContextHelp() looks up and returns context help and a title for that help text for the widget w. The returned strings must be freed with XtFree() when no longer needed.

XmtHelpGetContextHelp() looks these up by reading the xmtHelp and xmtHelpTitle pseudo-resources for the widget w. If the contextHelpFile application resource is specified, then the resource file it names will be read in the first time that XmtHelpGetContextHelp() is called, and all context help will be looked up in that special help database. If no special contextHelpFile is specified, then the context help pseudo-resources are queried from the default database.

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

SEE ALSO