falso
/
cdesktopenv
mirror of https://git.code.sf.net/p/cdesktopenv/code
1
0
Fork 0
Code Issues Releases Wiki Activity
cdesktopenv/cde/doc/C/guides/helpGuide/ch08.sgm

294 lines
17 KiB
Plaintext
Raw Blame History

<!-- $XConsortium: ch08.sgm /main/12 1996/09/08 19:40:25 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.CrDia.div.1">
<title id="HRDC.CrDia.mkr.1">Creating and Managing Help Dialog Boxes</title>
<para>This chapter describes the Help dialog widgets and how to create them.
</para>
<informaltable id="HRDC.CrDia.itbl.1" frame="All">
<tgroup cols="1">
<colspec colname="1" colwidth="4.0 in">
<tbody>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Help Dialog Boxes207'--><xref role="JumpText"
linkend="HRDC.CrDia.mkr.2"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'General Help Dialog208'--><xref role="JumpText"
linkend="HRDC.CrDia.mkr.3"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Create a General Help Dialog209'--><xref
role="JumpText" linkend="HRDC.CrDia.mkr.5"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Quick Help Dialog211'--><xref role="JumpText"
linkend="HRDC.CrDia.mkr.6"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'To Create a Quick Help Dialog211'--><xref
role="JumpText" linkend="HRDC.CrDia.mkr.7"></para></entry></row>
<row rowsep="1">
<entry><para><!--Original XRef content: 'Summary of Application Program Interface214'--><xref
role="JumpText" linkend="HRDC.CrDia.mkr.8"></para></entry></row></tbody></tgroup>
</informaltable>
<sect1 id="HRDC.CrDia.div.2">
<title id="HRDC.CrDia.mkr.2">Help Dialog Boxes</title>
<indexterm><primary>creating</primary><secondary>help dialog boxes</secondary>
</indexterm><indexterm><primary>managing help dialog boxes</primary></indexterm><indexterm><primary>dialog boxes</primary><secondary>creating and managing</secondary></indexterm><indexterm><primary>dialog boxes</primary><secondary>quick help</secondary></indexterm><indexterm><primary>dialog boxes</primary>
<secondary>general help</secondary></indexterm><indexterm><primary>general
help dialog box</primary><secondary>features</secondary></indexterm>
<para>For application programmers, the Help System provides a programming
library that adds help dialog boxes to any Motif application. The library
provides two types of help dialog boxes:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>General help dialogs</emphasis> have a menu bar, a topic tree, and a help topic display area.
The topic tree lists the help volume's topics and subtopics. Users use the
topic tree to select topics to view, to browse available topics, and to locate
where they are in the help volume.</para>
</listitem><listitem><para><emphasis>Quick help dialogs</emphasis> contain
a topic display area and one or more dialog buttons at the bottom.</para>
</listitem></itemizedlist>
<sect2 id="HRDC.CrDia.div.3">
<title>Standard Xt Paradigm<indexterm><primary>widget classes</primary>
</indexterm><indexterm><primary>class, dialog widgets</primary></indexterm></title>
<para><indexterm><primary>widget resources</primary></indexterm><indexterm>
<primary>resources</primary><secondary>help dialog boxes</secondary></indexterm>In
terms of programming, you interact with the help dialogs the same as you
do with any other Motif widgets in your applications. The two types of
help dialog boxes are defined as two new widget classes: <classname>DtHelpDialog</classname> and <classname>DtHelpQuickDialog</classname>.</para>
<para>Nearly every attribute of the help windows&mdash;including the volume
name and topic ID&mdash;are manipulated as widget resources. For instance,
to display a new topic, you just execute an <function>XtSetValues()</function>
call to set the <systemitem class="resource">DtNhelpVolume</systemitem>, <systemitem class="resource">DtNlocationId</systemitem>, and <systemitem class="resource">DtNhelpType</systemitem> resources. For more information, refer to <!--Original
XRef content: '&ldquo;Displaying Help Topics&rdquo;
on page&numsp;216'--><xref role="SecTitleAndPageNum" linkend="HRDC.HReq.mkr.3">.
</para>
<note>
<para>Integrating the Help System into an application requires a working
knowledge of the C programming language, the Motif programmer's toolkit,
and the Xt Intrinsics toolkit.</para>
</note>
</sect2>
</sect1>
<sect1 id="HRDC.CrDia.div.4">
<title id="HRDC.CrDia.mkr.3">General Help Dialog</title>
<para>A general help dialog has two display areas: the topic tree and topic
display area. The topic tree provides a scrollable list of help topics. The
home topic title is always the first item. When a user chooses a title, an
arrow (&rarr;) marks the title and its help information is displayed in the topic
display area. <!--Original XRef content:
'Figure&numsp;9&hyphen;1
on page&numsp;209'--><xref role="CodeOrFigOrTabAndPNum" linkend="hrdc.crdia.mkr.4">
shows the topic tree and topic display area of a general help window. The
current topic, &ldquo;To select a palette&rdquo;, is displayed.</para>
<para>The general help dialog includes three dialog buttons: Backtrack, History,
and Index. These commands are also available in the Help menus. For an overview
of the Help dialogs and the graphical user interface, refer to the section,
<!--Original XRef content: '&ldquo;Help
User Interface&rdquo; on page&numsp;5'--><xref role="SecTitleAndPageNum"
linkend="HRDC.Intro.mkr.7">.</para>
<para><indexterm><primary>general help dialog box</primary><secondary>features</secondary></indexterm><indexterm><primary>general help dialog box</primary>
<secondary>dialog buttons</secondary></indexterm><indexterm><primary>dialog
boxes</primary><secondary>general help</secondary></indexterm></para>
<figure>
<title id="HRDC.CrDia.mkr.4">General help dialog</title>
<graphic id="HRDC.CrDia.grph.1" entityref="HRDC.CrDia.fig.1"></graphic>
</figure>
<sect2 id="HRDC.CrDia.div.5" role="Procedure">
<title id="HRDC.CrDia.mkr.5">To Create a General Help Dialog<indexterm><primary>creating</primary><secondary>general help dialog box</secondary></indexterm><indexterm>
<primary>general help dialog box</primary><secondary>creating</secondary>
</indexterm><indexterm><primary>dialog boxes</primary><secondary>creating
general help</secondary></indexterm></title>
<orderedlist><listitem><para>Include the appropriate header files:</para>
<programlisting>#include &lt;Help.h>
#include &lt;HelpDialog.h></programlisting>
</listitem><listitem><para>Create an instance of the general help dialog widget:
</para>
<para>Use the <function moreinfo="RefEntry">DtCreateHelpDialog()</function>
convenience function.</para>
<para><emphasis>Or,</emphasis> use the <function moreinfo="RefEntry">XtCreateManagedWidget()</function> function.</para>
</listitem><listitem><para>Add a callback for handling hyperlink events that
occur within the dialog. (For more information, see <xref role="SecTitleAndPageNum"
linkend="HRDC.DiaEv.mkr.3">.)</para>
</listitem><listitem><para>Add a <emphasis>close callback</emphasis> for handling
the Close command.</para>
</listitem></orderedlist>
<sect3 id="HRDC.CrDia.div.6">
<title>Example</title>
<para>The following code segment creates a general help dialog (as a child
of <symbol role="Variable">parent</symbol>) using the convenience function.
The dialog is left unmanaged&mdash;presumably it is managed elsewhere in the
application when a help request is made.</para>
<programlisting>Widget mainHelpDialog, moreButton, helpButton;
ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpVolume, "My Help Volume"); ac++;
XtSetArg (al[ac], DtNlocationId, "Getting Started"); ac++;
XtSetArg (al[ac], DtNhelpType, "DtHELP_TYPE_TOPIC"); ac++;
mainHelpDialog =
DtCreateHelpDialog (parent, "mainHelpDialog", al, ac);</programlisting>
<para>The following two calls add the hyperlink and close callbacks to the
dialog. Presumably, the functions <function>HyperlinkCB()</function> and <function>CloseHelpCB()</function> are declared elsewhere in the application.</para>
<programlisting>XtAddCallback (mainHelpDialog, DtNhyperLinkCallback,
HyperlinkCB, (XtPointer)NULL);
XtAddCallback (mainHelpDialog, DtNcloseCallback,
CloseHelpCB, (XtPointer)NULL);</programlisting>
</sect3>
<sect3 id="HRDC.CrDia.div.7">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.H4Hlp.mkr.1"></para>
</listitem><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.DiaEv.mkr.7">
</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtCreateHelpDialog</filename>(3) man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpDialog</filename>(3)
man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrDia.div.8">
<title id="HRDC.CrDia.mkr.6">Quick Help Dialog</title>
<para><indexterm><primary>quick help dialog box</primary><secondary>buttons</secondary></indexterm>The quick help dialog box is designed to help you
meet the primary objective of online help: <emphasis>Get the user back on
task as quickly and successfully as possible.</emphasis> This simple user
interface helps keep the user focused on the information. The information
should be useful enough that the user dismisses the dialog after reading it
and continues working.</para>
<figure>
<title>Quick help dialog with four standard buttons</title>
<graphic id="HRDC.CrDia.grph.2" entityref="HRDC.CrDia.fig.2"></graphic>
</figure>
<para>The quick help dialog has five buttons, four of which are managed. The
remaining dialog button is configurable, so this button can be used for anything.
However, its intended purpose is to provide a path to more help in one of
these two ways:</para>
<itemizedlist><listitem><para>Let the user ask for more detailed information.
In this case, the default button label (More) is appropriate. This is called <emphasis>progressive disclosure</emphasis>.</para>
</listitem><listitem><para>Let the user open a general help dialog for general
browsing of the application's help volume. In this case, <literal>Browse&hellip;</literal> is the most appropriate button label.</para>
</listitem></itemizedlist>
<para>The Developer's toolkit includes a convenience function, <function>DtHelpQuickDialogGetChild()</function>, for determining the widget ID for
any of the quick help dialog buttons.</para>
<sect2 id="HRDC.CrDia.div.9" role="Procedure">
<title id="HRDC.CrDia.mkr.7">To Create a Quick Help Dialog</title>
<orderedlist><listitem><para>Include the appropriate header files:</para>
<programlisting>#include &lt;Help.h>
#include &lt;HelpQuickD.h></programlisting>
</listitem><listitem><para>Create an instance of the quick help dialog widget:
</para>
<itemizedlist><listitem><para>Use the <function moreinfo="refentry">DtCreateHelpQuickDialog()</function> convenience function.</para>
</listitem><listitem><para><emphasis>Or,</emphasis> use the <function moreinfo="refentry">
XtCreateManagedWidget()</function> function.</para>
</listitem></itemizedlist>
</listitem><listitem><para>Add a callback for handling hyperlink events that
occur within the dialog. (For more information, see <xref role="SecTitleAndPageNum"
linkend="HRDC.DiaEv.mkr.3">.)</para>
</listitem><listitem><para>Add a <emphasis>close callback</emphasis> for handling
the OK button.</para>
</listitem><listitem><para>Configure the dialog buttons that you want to use:
</para>
<itemizedlist><listitem><para>If you intend to use the application-configured
button, manage it and add an activate callback.</para>
</listitem><listitem><para>If you want to disallow printing, unmanage the
Print button.</para>
</listitem><listitem><para>Manage the Help button and add a <emphasis>help
callback</emphasis> to the dialog to allow the user to get &ldquo;help on
help.&rdquo;</para>
</listitem></itemizedlist>
</listitem></orderedlist>
<sect3 id="HRDC.CrDia.div.10">
<title>Example</title>
<para>The following code segment creates a quick help dialog (as a child of <symbol>parent</symbol>) using the convenience function. The dialog is left unmanaged;
presumably, it is managed elsewhere in the application when a help request
is made. In this example, the application-configured button is enabled and
used to request more help.</para>
<programlisting>Widget quickHelpDialog, moreButton, helpButton;
ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;
XtSetArg (al[ac], DtNhelpVolume, "My Help Volume"); ac++;
XtSetArg (al[ac], DtNlocationId, "Getting Started"); ac++;
XtSetArg (al[ac], DtNhelpType, "DtHELP;_TYPE_TOPIC"); ac++;
quickHelpDialog =
DtCreateHelpQuickDialog (<symbol>parent</symbol>, "quickHelpDialog", al, ac);
</programlisting>
<para>The following two calls add the hyperlink and close callbacks to the
dialog. Presumably, the functions <function>HyperlinkCB()</function> and <function>CloseHelpCB()</function> are declared elsewhere in the application.</para>
<programlisting>XtAddCallback (quickHelpDialog, DtNhyperLinkCallback,
HyperlinkCB, (XtPointer)NULL);
XtAddCallback (quickHelpDialog, DtNcloseCallback,
CloseHelpCB, (XtPointer)NULL);
</programlisting>
<para>Here, the application-configured button is managed and assigned an activate
callback that invokes the application's <function>MoreHelpCB()</function>
function.</para>
<programlisting>moreButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DT_HELP_QUICK_MORE_BUTTON);
XtManageChild (moreButton);
XtAddCallback (moreButton, XmNactivateCallback,
MoreHelpCB, (XtPointer)NULL);
</programlisting>
<para>To provide &ldquo;help on help,&rdquo; the dialog's Help button is managed
and a help callback is added to the dialog.</para>
<programlisting>helpButton = DtHelpQuickDialogGetChild (quickHelpDialog,
DT_HELP_QUICK_HELP_BUTTON);
XtManageChild (helpButton);
XtAddCallback (quickHelpDialog,DtNhelpCallback,
HelpRequestCB, USING_HELP);
</programlisting>
<para>Like other Motif dialogs, when you add a help callback to a quick
help dialog, it is used by both the F1 key and the Help button.</para>
</sect3>
<sect3 id="HRDC.CrDia.div.11">
<title>See Also</title>
<itemizedlist><listitem><para><xref role="SecTitleAndPageNum" linkend="HRDC.DiaEv.mkr.7"></para>
</listitem><listitem><para><xref role="ChapNumAndTitle" linkend="HRDC.H4Hlp.mkr.1"></para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtCreateHelpQuickDialog</filename>(3) man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpQuickDialog</filename>(3) man page</para>
</listitem><listitem><para><filename moreinfo="RefEntry">DtHelpQuickDialogGetChild</filename>(3) man page</para>
</listitem></itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="HRDC.CrDia.div.12">
<title id="HRDC.CrDia.mkr.8">Summary of Application Program Interface</title>
<para>Related man pages for the Help System are:</para>
<itemizedlist><listitem><para>Functions for creating and working with dialogs:
</para>
<itemizedlist><listitem><para><filename>DtHelp(5)</filename></para>
</listitem><listitem><para><filename>DtHelpDialog(5)</filename></para>
</listitem><listitem><para><filename>DtHelpQuickD(5)</filename></para>
</listitem><listitem><para><function>DtCreateHelpDialog()</function></para>
</listitem><listitem><para><function>DtCreateHelpQUickDialog()</function></para>
</listitem><listitem><para><function>DtHelpQuickDialogGetChild()</function></para>
</listitem></itemizedlist>
</listitem><listitem><para>Function for implementing item help mode:</para>
<itemizedlist><listitem><para><function>DtHelpReturnSelectedWidgetId()</function></para>
</listitem></itemizedlist>
</listitem><listitem><para>Function for specifying the message catalog for
the Help library:</para>
<itemizedlist><listitem><para><function>DtHelpSetCatalogName()</function></para>
</listitem></itemizedlist>
</listitem><listitem><para>Applications and actions for creating and viewing
a help volume:</para>
<itemizedlist><listitem><para><filename>dtdocbook</filename>(1)</para>
</listitem><listitem><para><filename>dthelpview</filename>(1)</para>
</listitem><listitem><para><filename>dthelpgen</filename>(1)</para>
</listitem><listitem><para><filename>dthelpaction(5)</filename></para>
</listitem><listitem><para><filename>dtmanaction(5)</filename></para>
</listitem></itemizedlist>
</listitem><listitem><para>Document Type Definitions:</para>
<itemizedlist><listitem><para><filename>dtdocbookdtd(4)</filename></para>
</listitem><listitem><para><filename>dtsdldtd(4)</filename></para>
</listitem></itemizedlist>
</listitem><?Pub Caret1></itemizedlist>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
Reference in New Issue View Git Blame Copy Permalink