580 lines
30 KiB
Plaintext
580 lines
30 KiB
Plaintext
<!-- $XConsortium: ch09.sgm /main/10 1996/09/08 19:40:34 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="HRDC.HReq.div.1">
|
|
<title id="HRDC.HReq.mkr.1">Responding to Help Requests</title>
|
|
<para>This chapter explains how to display different types of help information
|
|
by setting Help Dialog widget resources.</para>
|
|
<informaltable id="HRDC.HReq.itbl.1" frame="All">
|
|
<tgroup cols="1">
|
|
<colspec colname="1" colwidth="4.0 in">
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Requesting Help215'--><xref role="JumpText"
|
|
linkend="HRDC.HReq.mkr.2"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Displaying Help Topics216'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.3"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Display a Help Topic217'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.5"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Display a String of Text218'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.6"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Display a Text File219'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.7"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'To Display a Man Page220'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.8"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Enabling the Help Key (F1)220'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.9"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Providing a Help Menu224'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.11"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Supporting Item Help Mode225'--><xref
|
|
role="JumpText" linkend="HRDC.HReq.mkr.12"></para></entry></row></tbody></tgroup>
|
|
</informaltable>
|
|
<sect1 id="HRDC.HReq.div.2">
|
|
<title id="HRDC.HReq.mkr.2">Requesting Help</title>
|
|
<indexterm><primary>responding to</primary><secondary>help requests</secondary>
|
|
</indexterm><indexterm><primary>requests, responding to help</primary></indexterm>
|
|
<para>When a user requests help while using your application, it is the application's
|
|
responsibility to determine what help topic should be displayed.</para>
|
|
<sect2 id="HRDC.HReq.div.3">
|
|
<title>Context Sensitivity</title>
|
|
<para>Some help requests amount to an explicit request for specific information,
|
|
such as help on “version” (which usually displays the copyright
|
|
topic). Other help requests, however, may require some degree of context sensitivity.
|
|
That is, some processing might be needed to determine the appropriate help
|
|
topic based on the user's current context within the application.</para>
|
|
<para>For instance, your application might test the status of certain modes
|
|
or settings to determine the appropriate help topic. Or, it might test the
|
|
value of an input field and provide detailed help if the value is not valid,
|
|
and general help if the value is valid.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.HReq.div.4">
|
|
<title>Entry Points</title>
|
|
<para>An <emphasis>entry point</emphasis> is a specific location within a
|
|
help volume—usually the beginning of a topic—that can be directly
|
|
accessed by requesting help within the application.</para>
|
|
<para>From the author's point of view, entry points are established by assigning
|
|
IDs at the appropriate places within the help volume. From the programmer's
|
|
point of view, entry points are created by enabling the user to request help
|
|
and using the appropriate ID when a particular request is made.</para>
|
|
<para>There are four general ways for users to request help:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Pressing the <emphasis>help
|
|
key</emphasis> (which is F1 on most keyboards)</para>
|
|
</listitem><listitem><para>Clicking the Help button in a dialog box</para>
|
|
</listitem><listitem><para>Choosing a command from the application's Help
|
|
menu</para>
|
|
</listitem><listitem><para>Choosing On Item help</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.HReq.div.5">
|
|
<title id="HRDC.HReq.mkr.3">Displaying Help Topics</title>
|
|
<para>When a help request is made, the application determines what help topic
|
|
to display. It then creates (if necessary) and manages a help dialog, and
|
|
sets the appropriate resources to display a help topic.</para>
|
|
<para>Most requests display help topics that are part of the application's
|
|
help volume, but the Help System's help dialogs are also capable of displaying
|
|
man pages, text files, and simple text strings.</para>
|
|
<para id="HRDC.HReq.mkr.4">The Help System's help dialogs are based exclusively
|
|
on Xt Intrinsics and Motif programming, so you change the values within
|
|
a help dialog just like any other widget: by setting resources.</para>
|
|
<para>The <systemitem class="resource">DtNhelpType</systemitem> resource determines
|
|
what type of information is displayed. It can be set to any of these values:
|
|
</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><systemitem class="constant">DtHELP_TYPE_TOPIC</systemitem> for displaying normal help topics that are
|
|
part of a help volume. The volume is specified by setting the <systemitem class="resource">DtNhelpVolume</systemitem> resource; the topic is specified
|
|
by setting <systemitem class="resource">DtNLocationId</systemitem> resource.
|
|
</para>
|
|
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_STRING</systemitem> for displaying a string supplied by the application. Automatic
|
|
word wrap is disabled, so line breaks are observed as specified in the string.
|
|
The string is specified by setting the <systemitem class="resource">DtNstringData</systemitem> resource.</para>
|
|
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_DYNAMIC_STRING</systemitem> for displaying a string supplied by the application, using word
|
|
wrap to format the text. Line breaks within the string are used to separate
|
|
paragraphs. The string is specified by setting the <systemitem class="resource">DtNstringData</systemitem> resource.</para>
|
|
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_FILE</systemitem>
|
|
for displaying a text file. The name of the file to be displayed is specified
|
|
by setting the <systemitem class="resource">DtNhelpFile</systemitem> resource.
|
|
</para>
|
|
</listitem><listitem><para><systemitem class="constant">DtHELP_TYPE_MAN_PAGE</systemitem> for displaying a manual reference page (man page) in a help
|
|
dialog. The man page to be displayed is specified by setting the <systemitem class="resource">DtNmanPage</systemitem> resource.</para>
|
|
</listitem></itemizedlist>
|
|
<para>These values are defined in the <filename>Help.h</filename> file.</para>
|
|
<sect2 id="HRDC.HReq.div.6">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.CrDia.mkr.1"></para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.HReq.div.7" role="Procedure">
|
|
<title id="HRDC.HReq.mkr.5">To Display a Help Topic</title>
|
|
<orderedlist><listitem><para>Create a help dialog.</para>
|
|
</listitem><listitem><para>Set the following resources for the help dialog:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="164*">
|
|
<colspec align="left" colwidth="364*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpType</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_TOPIC</systemitem>.</para></entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpVolume</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to the volume name for your application.
|
|
</para></entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNlocationId</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to the topic ID that you want to
|
|
display.</para></entry></row></tbody></tgroup></informaltable>
|
|
<para>You can also set other values for the dialog, such as its size and title.
|
|
</para>
|
|
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.HReq.div.8">
|
|
<title>Example</title>
|
|
<para>This program segment displays a topic with the ID <symbol>getting-started</symbol> in the volume <filename>MyVolume</filename>.</para>
|
|
<programlisting>ac = 0;
|
|
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_TOPIC); ac++;
|
|
XtSetArg (al[ac], DtNhelpVolume, “MyVolume”); ac++;
|
|
XtSetArg (al[ac], DtNlocationId, “getting-started”); ac++;
|
|
XtSetArg (al[ac], DtNcolumns, 40); ac++;
|
|
XtSetArg (al[ac], DtNrows, 12); ac++;
|
|
XtSetValues (helpDialog, al, ac);
|
|
XtManageChild (helpDialog);</programlisting>
|
|
<para>If the help volume <filename>MyVolume</filename> is not registered,
|
|
then a complete path to the <filename>MyVolume.sdl</filename> file is required
|
|
for the value of <systemitem class="resource">DtNhelpVolume</systemitem>.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.HReq.div.9" role="Procedure">
|
|
<title id="HRDC.HReq.mkr.6">To Display a String of Text</title>
|
|
<orderedlist><listitem><para>Create a quick help dialog.</para>
|
|
<para>You can use a general help dialog to display string data, but this isn't
|
|
recommended because most of its features do not apply to string data.</para>
|
|
</listitem><listitem><para>Set the following resources for the help dialog:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="177*">
|
|
<colspec align="left" colwidth="351*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpType</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_DYNAMIC_STRING</systemitem> (if you want word wrap enabled) or <systemitem class="constant">DtHELP_TYPE_STRING</systemitem> (if you want the line breaks
|
|
within the string to be maintained)</para></entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNstringData</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to the string you want to display.
|
|
A copy of the string is kept internally, so you need not maintain your copy
|
|
of it.</para></entry></row></tbody></tgroup></informaltable>
|
|
<para>You can also set other values for the dialog, such as its size and title.
|
|
</para>
|
|
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.HReq.div.10">
|
|
<title>Example</title>
|
|
<para>This program segment displays a string stored in the variable <symbol role="Variable">descriptionString</symbol>.</para>
|
|
<programlisting>ac = 0;
|
|
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_DYNAMIC_STRING); ac++;
|
|
XtSetArg (al[ac], DtNstringData, (char *)descriptionString); ac++;
|
|
XtSetValues (quickHelpDialog, al, ac);
|
|
XtManageChild (quickHelpDialog);</programlisting>
|
|
<para>If the string is no longer needed within the application, the memory
|
|
can be freed, because the help dialog makes its own copy of the data.</para>
|
|
<programlisting>XtFree (descriptionString);</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.HReq.div.11" role="Procedure">
|
|
<title id="HRDC.HReq.mkr.7">To Display a Text File</title>
|
|
<orderedlist><listitem><para>Create a quick help dialog or retrieve one from
|
|
your dialog cache.</para>
|
|
<para>You can use a general help dialog to display a text file, but this isn't
|
|
recommended because most of its features are useful only for standard help
|
|
topics.</para>
|
|
</listitem><listitem><para>Set the following resources for the help dialog:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="159*">
|
|
<colspec align="left" colwidth="369*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="prompt">DtNhelpType</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_FILE</systemitem>.</para></entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="prompt">DtNhelpFile</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to the file name you want to display.
|
|
If the file is not in the application's current directory, provide a path
|
|
to the file.</para></entry></row></tbody></tgroup></informaltable>
|
|
<para>You can also set other values for the dialog, such as its size and title.
|
|
In particular, you might want to set the width to 80 columns, which is the
|
|
standard width for text files.</para>
|
|
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.HReq.div.12">
|
|
<title>Example</title>
|
|
<para>The following program segment displays a file named <filename>/tmp/printer.list</filename>. It also sets the size of the dialog to better suit a text file.
|
|
</para>
|
|
<programlisting>ac = 0;
|
|
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_FILE); ac++;
|
|
XtSetArg (al[ac], DtNhelpFile, “/tmp/printer.list”); ac++;
|
|
XtSetArg (al[ac], DtNcolumns, 80); ac++;
|
|
XtSetArg (al[ac], DtNrows, 20); ac++;
|
|
XtSetValues (quickHelpDialog, al, ac);
|
|
XtManageChild (quickHelpDialog);</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.HReq.div.13" role="Procedure">
|
|
<title id="HRDC.HReq.mkr.8">To Display a Man Page</title>
|
|
<indexterm><primary>displaying</primary><secondary>man page</secondary></indexterm>
|
|
<indexterm><primary>man page</primary><secondary>displaying</secondary></indexterm>
|
|
<indexterm><primary><Filename | Command>DtHELP_TYPE_MAN_PAGE <Default Para Font></primary></indexterm>
|
|
<orderedlist><listitem><para>Create a quick help dialog.</para>
|
|
<para>You can use a general help dialog to display a man page, but this isn't
|
|
recommended because most of its features are useful only with standard help
|
|
topics.</para>
|
|
</listitem><listitem><para>Set the following resources for the help dialog:
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="159*">
|
|
<colspec align="left" colwidth="369*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNhelpType</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to <systemitem class="constant">DtHELP_TYPE_MAN_PAGE</systemitem>.</para></entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><systemitem class="resource">DtNmanPage</systemitem></para></entry>
|
|
<entry align="left" valign="top"><para>Set to the name of the man page. The
|
|
value of this resource is passed directly to the system <command>man</command>
|
|
command. So, to specify a particular section of a man page, precede the man
|
|
page name by a section number, just as you would if you were typing the <command>man</command> command conventionally.</para></entry></row></tbody></tgroup>
|
|
</informaltable>
|
|
<para>You can also set other values for the dialog, such as its size and title.
|
|
</para>
|
|
</listitem><listitem><para>Manage the dialog using <function>XtManageChild()</function>.</para>
|
|
</listitem></orderedlist>
|
|
<sect3 id="HRDC.HReq.div.14">
|
|
<title>Example</title>
|
|
<para>The following program segment displays the man page for the <command>grep</command> command. It also sets the size of the dialog to better suit
|
|
a man page.</para>
|
|
<programlisting>ac = 0;
|
|
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_MAN_PAGE); ac++;
|
|
XtSetArg (al[ac], DtNmanPage, “grep”); ac++;
|
|
XtSetArg (al[ac], DtNcolumns, 80); ac++;
|
|
XtSetArg (al[ac], DtNrows, 20); ac++;
|
|
XtSetValues (quickHelpDialog, al, ac);
|
|
XtManageChild (quickHelpDialog);</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.HReq.div.15">
|
|
<title id="HRDC.HReq.mkr.9">Enabling the Help Key (F1)</title>
|
|
<indexterm><primary>F1 (help key)</primary></indexterm><indexterm><primary>key, enabling help (F1)</primary></indexterm><indexterm><primary>help key</primary></indexterm>
|
|
<para>The <emphasis>help key</emphasis> mechanism is a feature built into
|
|
all Motif manager widgets and primitive widgets. The help key is enabled
|
|
by adding a <emphasis>help callback</emphasis> to the widget where you want
|
|
the help key active.</para>
|
|
<para>Within your application, you should add a help callback to each widget
|
|
where you want a unique entry point into help. The help callback mechanism
|
|
automatically “walks” up the widget hierarchy (up to the shell
|
|
widget) until it finds a widget with a help callback, then invokes that callback.
|
|
</para>
|
|
<para>If you add a help callback to a manager widget, when the help key is
|
|
pressed for any of its children, the manager's help callback is invoked (unless
|
|
the child widget has a help callback of its own).</para>
|
|
<sect2 id="HRDC.HReq.div.16" role="Procedure">
|
|
<title id="HRDC.HReq.mkr.10">To Add a Help Callback</title>
|
|
<para>Use the <function>XtAddCallback()</function> function as follows:</para>
|
|
<programlisting>XtAddCallback (
|
|
Widget widget,
|
|
String DtNhelpCallback,
|
|
XtCallbackProc HelpRequestCB,
|
|
XtPointer clientData );
|
|
|
|
</programlisting>
|
|
<para>Where:</para>
|
|
<informaltable>
|
|
<tgroup cols="2" colsep="0" rowsep="0">
|
|
<colspec align="left" colwidth="170*">
|
|
<colspec align="left" colwidth="358*">
|
|
<tbody>
|
|
<row>
|
|
<entry align="left" valign="top"><para><symbol role="Variable">widget</symbol></para></entry>
|
|
<entry align="left" valign="top"><para>The widget where you want to activate
|
|
the help key.</para></entry></row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><function role="Variable">HelpRequestCB()</function></para></entry>
|
|
<entry align="left" valign="top"><para>The function in your application that
|
|
handles the help request when the user presses the help key.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="left" valign="top"><para><symbol role="Variable">clientData</symbol></para></entry>
|
|
<entry align="left" valign="top"><para>The data you want passed to the <function>HelpRequestCB()</function>function. Typically, this data identifies the topic
|
|
to be displayed.</para></entry></row></tbody></tgroup></informaltable>
|
|
<para>When the user presses the help key, the help callback is invoked for
|
|
the widget with the current keyboard focus. If that widget does not have a
|
|
help callback, the help callback for its nearest ancestor that does have a
|
|
help callback is invoked.</para>
|
|
<para>If no help callbacks are found, nothing happens. Therefore, it is recommended
|
|
that you add a help callback to each shell in your application. This ensures
|
|
that no user requests for help are lost.</para>
|
|
<para>Adding a help callback to a dialog shell automatically enables the Help
|
|
button on the dialog to invoke the help callback.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.HReq.div.17">
|
|
<title>Importance of Client Data</title>
|
|
<para>Specifying a unique value for <symbol role="Variable">clientData</symbol>
|
|
in each help callback you add saves you the trouble of writing a separate
|
|
function to process each help callback. Your application can have a single
|
|
callback procedure to process all help requests (see <xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.HReq.mkr.10">). Within the callback procedure, use the <symbol role="Variable">clientData</symbol> to identify where the user requested help.
|
|
That is, each time you add a help callback, you should provide a unique value
|
|
for <symbol role="Variable">clientData</symbol>.</para>
|
|
<sect3 id="HRDC.HReq.div.18">
|
|
<title>Example</title>
|
|
<para>The following example demonstrates one way to associate IDs with entry
|
|
points. A <filename>HelpEntryIds.h</filename> file is used to define a unique
|
|
integer for each <symbol role="Variable">clientData</symbol> value for each
|
|
help callback. Also defined are two ID strings for each widget: one for normal
|
|
F1 help, the other for item help mode (where the user picks a widget to get
|
|
a description).</para>
|
|
<para>For this example, assume that the application's user interface is just
|
|
a main window with three input fields: Name, Address, and Telephone Number.
|
|
Here's what the <filename>HelpEntryIds.h</filename> file would contain:</para>
|
|
<programlisting>#define HELP_volumeName "MyVolume"
|
|
#define HELP_MainWindow 100
|
|
#define HELP_MainWindow_ID "basic-tasks"
|
|
#define HELP_MainWindow_ITEM_ID "main-window-desc"
|
|
|
|
#define HELP_NameField 101
|
|
#define HELP_NameField_ID "specifying-a-name"
|
|
#define HELP_NameField_ITEM_ID "name-field-desc"
|
|
|
|
#define HELP_AddressField 102
|
|
#define HELP_AddressField_ID "specifying-an-address"
|
|
#define HELP_AddressField_ITEM_ID "address-field-desc"
|
|
|
|
#define HELP_PhoneField 103
|
|
#define HELP_PhoneField_ID "specifying-a-phone-no"
|
|
#define HELP_PhoneField_ITEM_ID "phone-field-desc"</programlisting>
|
|
<para>Within the part of the application that initially creates the widgets,
|
|
a help callback is added to each widget as follows:</para>
|
|
<programlisting>XtAddCallback (mainWindow, DtNhelpCallback,
|
|
HelpRequestCB, HELP_MainWindow);
|
|
XtAddCallback (nameField, DtNhelpCallback,
|
|
HelpRequestCB, HELP_NameField);
|
|
XtAddCallback (addressField, DtNhelpCallback,
|
|
HelpRequestCB, HELP_AddressField);
|
|
XtAddCallback (phoneField, DtNhelpCallback,
|
|
HelpRequestCB, HELP_PhoneField);</programlisting>
|
|
<para>Within the <function>HelpRequestCB()</function> function, the <symbol role="Variable">clientData</symbol> parameter is used to dispatch the help
|
|
requests (through a <command>switch()</command> statement). Within each case,
|
|
the value of a global flag <systemitem class="environvar">itemHelp</systemitem>
|
|
is tested to see if the help callback was invoked by the F1 key (the flag
|
|
is “false”) or by the user picking the widget in item help mode
|
|
(the flag is “true”).</para>
|
|
<programlisting>XtCallbackProc HelpRequestCB (
|
|
Widget w,
|
|
XtPointer clientData,
|
|
XtPointer callData)
|
|
{
|
|
char *topicToDisplay;
|
|
Boolean useQuickHelpDialog;
|
|
/* <emphasis>Determine the topic ID for the given `clientData.'</emphasis> */
|
|
switch ((int)clientData)
|
|
{
|
|
case HELP_MainWindow:
|
|
useQuickHelpDialog = False;
|
|
if (itemHelpFlag)
|
|
topicToDisplay = HELP_MainWindow_ITEM_ID;
|
|
else
|
|
topicToDisplay = HELP_MainWindow_ID;
|
|
break; case HELP_NameField:
|
|
useQuickHelpDialog = True;
|
|
if (itemHelpFlag)
|
|
topicToDisplay = HELP_NameField_ITEM_ID;
|
|
else
|
|
topicToDisplay = HELP_NameField_ID;
|
|
break; case HELP_AddressField:
|
|
useQuickHelpDialog = True;
|
|
if (itemHelpFlag)
|
|
topicToDisplay = HELP_AddressField_ITEM_ID;
|
|
else
|
|
topicToDisplay = HELP_AddressField_ID;
|
|
break; case HELP_PhoneField:
|
|
useQuickHelpDialog = True;
|
|
if (itemHelpFlag)
|
|
topicToDisplay = HELP_PhoneField_ITEM_ID;
|
|
else
|
|
topicToDisplay = HELP_PhoneField_ID;
|
|
break; default:
|
|
/* <emphasis>An unknown clientData was received.</emphasis> */
|
|
/* <emphasis>Put your error handling code here.</emphasis> */
|
|
return;
|
|
break;
|
|
}
|
|
/* <emphasis>Display the topic.</emphasis> */
|
|
ac = 0;
|
|
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_TOPIC); ac++;
|
|
XtSetArg (al[ac], DtNhelpVolume, HELP_volumeName); ac++;
|
|
XtSetArg (al[ac], DtNhelpType, topicToDisplay); ac++;
|
|
if (useQuickHelpDialog)
|
|
{
|
|
XtSetValues (mainQuickHelpDialog, al, ac);
|
|
XtManageChild (mainQuickHelpDialog);
|
|
}
|
|
else
|
|
{
|
|
XtSetValues (mainHelpDialog, al, ac);
|
|
XtManageChild (mainHelpDialog);
|
|
}
|
|
/* <emphasis>Clear the `item help' flag.</emphasis> */
|
|
itemHelpFlag = False;
|
|
}
|
|
|
|
</programlisting>
|
|
<para>The preceding function assumes that the application uses two help dialogs
|
|
for all help requests (<command>mainHelpDialog</command> and <command>mainQuickHelpDialog</command>), and that those dialogs have already been created. It also assumes
|
|
that <command>al</command> and <command>ac</command> (used in assembling
|
|
Xt argument lists) are declared elsewhere.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.HReq.div.19">
|
|
<title id="HRDC.HReq.mkr.11">Providing a Help Menu<indexterm><primary>help
|
|
menu, providing</primary></indexterm><indexterm><primary>menu</primary><secondary>providing help menu</secondary></indexterm></title>
|
|
<para>The <citetitle>Style Guide and Certification Checklist</citetitle> recommends
|
|
that each menu bar include a Help menu. The Help menu may contain a variety
|
|
of commands that lets the user access different types of online help for your
|
|
application.</para>
|
|
<para>The most important commands include:</para>
|
|
<itemizedlist><listitem><para><command>Introduction</command> displays the
|
|
home topic of your application's help, allowing the user to use hyperlinks
|
|
to navigate to any desired information.</para>
|
|
</listitem><listitem><para><command>Using Help</command> displays “help”
|
|
on help. This is information that tells the user how to use the Help System.
|
|
</para>
|
|
</listitem><listitem><para><command>Version</command> displays your application's
|
|
version and copyright information.</para>
|
|
</listitem></itemizedlist>
|
|
<para>Additional commands may display help on special keyboard usage, application
|
|
tasks, reference, or tutorials. You should design your Help menu to best suit
|
|
your application, while staying within the guidelines and recommendations
|
|
of the <citetitle>Style Guide and Certification Checklist.</citetitle></para>
|
|
<sect2 id="HRDC.HReq.div.20">
|
|
<title>See Also</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.OrgH.mkr.13"> describes how authors create the<?Pub Caret> home
|
|
topic for a help volume.</para>
|
|
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.16">
|
|
describes how authors create a copyright topic.</para>
|
|
</listitem><listitem><para><xref role="ChapNumAndTitle" linkend="HRDC.H4Hlp.mkr.1">describes
|
|
how help on help is found and how to add it to your application.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.HReq.div.21">
|
|
<title id="HRDC.HReq.mkr.12">Supporting Item Help Mode</title>
|
|
<para>Some applications provide an On Item or Help Mode command in their Help
|
|
menu. This command temporarily redefines the mouse pointer as a <literal>?</literal> (question mark) to prompt the user to select an item on the screen.
|
|
When an item is selected, the application is expected to display a description
|
|
of the item.</para>
|
|
<para>The convenience function, <function>DtHelpReturnSelectedWidgetId()</function>,
|
|
changes the pointer to a question mark and waits for the user to pick a widget.
|
|
The ID of the selected widget is returned. This function is similar to the <function>XmTrackingLocate()</function> function except that <function>DtHelpReturnSelectedWidgetId()</function> returns NULL if the user presses Escape to cancel the operation.
|
|
</para>
|
|
<para>To display help on the selected item, your application can simply invoke
|
|
the help callback for the returned widget. This is equivalent to the user
|
|
pressing <KeyCap>F1</KeyCap> while using that widget.</para>
|
|
<para>If you want the application to differentiate between item help and F1
|
|
help, you can set a flag before calling the widget's help callback. The help
|
|
callback procedure can then use that flag to determine that the callback was
|
|
invoked as a result of item help and alter its response accordingly.</para>
|
|
<sect2 id="HRDC.HReq.div.22" role="Procedure">
|
|
<title id="HRDC.HReq.mkr.13">To Add Support for Item Help</title>
|
|
<orderedlist><listitem><para>Write a function that uses the <function>DtHelpReturnSelectedWidgetId()</function> function. Within this function, invoke the help callback for the
|
|
selected widget. In the following steps, this function is called
|
|
<function>ProcessOnItemHelp()</function>, but you can name it whatever you want.</para>
|
|
</listitem><listitem><para>Add to your Help menu a command button labeled
|
|
<command>On Item</command>. Add an activate callback that invokes your
|
|
<function>ProcessOnItemHelp()</function> function.</para>
|
|
</listitem><listitem><para>Add a help callback to each widget in your application
|
|
where you want item help to be available.</para>
|
|
</listitem></orderedlist>
|
|
<para>If the selected widget does not have a help callback, the application
|
|
should try its parent widget. Similarly, if the parent does not have a help
|
|
callback, the application should continue to walk up the widget hierarchy
|
|
until it finds a help callback.</para>
|
|
<sect3 id="HRDC.HReq.div.23">
|
|
<title>Example</title>
|
|
<para>The following procedure is a sample <function>ProcessOnItemHelp()</function>
|
|
function that would be invoked by choosing <command>On Item</command> from
|
|
the Help menu.</para>
|
|
<programlisting>void ProcessOnItemHelp(
|
|
Widget widget)
|
|
{
|
|
/* <emphasis>Declare a variable for the selected widget.</emphasis> */
|
|
Widget selWidget=NULL;
|
|
int status=DtHELP_SELECT_ERROR;
|
|
/* <emphasis>Get an application shell widget from our widget hierarchy to
|
|
* pass into DtHelpReturnSelectedWidgetId().</emphasis> */
|
|
|
|
while (!XtIsSubclass(widget, applicationShellWidgetClass))
|
|
widget = XtParent(widget);
|
|
status = DtHelpReturnSelectedWidgetId(widget, NULL, &selWidget);
|
|
switch ((int)status)
|
|
{
|
|
case DtHELP_SELECT_ERROR:
|
|
printf(“Selection Error, cannot continue\n”);
|
|
break;
|
|
case DtHELP_SELECT_VALID:
|
|
/* <emphasis>We have a valid widget selection, now let's look
|
|
for a registered help callback to invoke.</emphasis> */
|
|
|
|
while (selWidget != NULL)
|
|
{
|
|
if ((XtHasCallbacks(selWidget, XmNhelpCallback)
|
|
== XtCallbackHasSome))
|
|
{
|
|
/* <emphasis>Found a help callback, so just call it</emphasis> */
|
|
XtCallCallbacks((Widget)selWidget,
|
|
XmNhelpCallback,NULL);
|
|
break;
|
|
}
|
|
else
|
|
/* <emphasis>No help callback on current widget, so try
|
|
the widget's parent</emphasis> */
|
|
selWidget = XtParent(selWidget);
|
|
}
|
|
break;
|
|
case DtHELP_SELECT_ABORT:
|
|
printf("Selection Aborted by user.\n");
|
|
break;
|
|
case DtHELP_SELECT_INVALID:
|
|
printf("You must select a component within your app.\n");
|
|
break;
|
|
}
|
|
}
|
|
|
|
</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
|
|
<?Pub *0000036813>
|