260 lines
16 KiB
Plaintext
260 lines
16 KiB
Plaintext
<!-- $XConsortium: appb.sgm /main/6 1996/08/25 15:09:01 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. -->
|
|
<appendix id="DKSUG.convf.div.1">
|
|
<title>dtksh Convenience Functions<indexterm><primary>convenience functions</primary></indexterm></title>
|
|
<para>The <command>dtksh</command> utility includes a file of convenience
|
|
functions. This file is itself a shell script containing shell functions
|
|
that may be useful to a shell programmer. The shell functions perform operations
|
|
that <command>dtksh</command> programmers frequently have to do for themselves.
|
|
These include functions for quickly creating certain kinds of dialogs (help,
|
|
error, warning, and so on), a function for easily creating a collection of
|
|
buttons, and functions that make it easier to configure the constraint resources
|
|
for a child of a form widget. It is not a requirement that shell script
|
|
writers use these convenience functions; they are supplied to make it easier
|
|
for developers to write shorter and more readable shell scripts.</para>
|
|
<para>Before a shell script can access these functions, it must first include
|
|
the file containing the convenience functions. The convenience functions
|
|
are located in the file <filename>/usr/dt/scripts/DtFuncs.sh.</filename>
|
|
Use the following notation to include them in a shell script:</para>
|
|
<programlisting>. /usr/dt/lib/dtksh/DtFuncs.dtsh</programlisting>
|
|
<sect1 id="DKSUG.convf.div.2">
|
|
<title>DtkshAddButtons<indexterm><primary>DtkshAddButtons</primary></indexterm></title>
|
|
<para><command>DtkshAddButtons</command> adds one or more buttons of the same
|
|
kind into a composite widget. It is most often used to add a collection
|
|
of buttons into a menupane or menubar.</para>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshAddButtons parent widgetClass label1 callback1
|
|
[label2 callback2 ...]
|
|
DtkshAddButtons [-w] parent widgetClass variable1 label1 callback1 \
|
|
[variable2 label2 callback2 ...]</programlisting>
|
|
<para>The <filename>-w</filename> option indicates that the convenience function
|
|
should return the widget handle for each of the buttons it creates. The
|
|
widget handle is returned in the specified environment variable. The <command>widgetClass</command> parameter can be set to any of the following, but it
|
|
defaults to <command>XmPushButtonGadget</command> if nothing is specified.
|
|
</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><command>XmPushButton</command></para>
|
|
</listitem><listitem><para><command>XmPushButtonGadget</command></para>
|
|
</listitem><listitem><para><command>XmToggleButton</command></para>
|
|
</listitem><listitem><para><command>XmToggleButtonGadget</command></para>
|
|
</listitem><listitem><para><command>XmCascadeButton</command></para>
|
|
</listitem><listitem><para><command>XmCascadeButtonGadget</command></para>
|
|
</listitem></itemizedlist>
|
|
<para>Examples:</para>
|
|
<programlisting>DtkshAddButtons $MENU XmPushButtonGadget Open do_Open Save do_Save
|
|
Quit exit
|
|
DtkshAddButtons -w $MENU XmPushButtonGadget B1 Open do_Open B2 Save
|
|
do_Save</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.3">
|
|
<title>DtkshSetReturnKeyControls<indexterm><primary>DtkshSetReturnKeyControls</primary></indexterm></title>
|
|
<para><command>DtkshSetReturnKeyControls</command> configures a text widget
|
|
within a form widget so that the Return key does not activate the default
|
|
button within the form, but instead moves the focus to the next text widget
|
|
within the form. This is useful if you have a window that contains a series
|
|
of text widgets, and the default button should not be activated until the
|
|
user presses the Return key while the focus is in the last text widget.</para>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshSetReturnKeyControls textWidget nextTextWidget formWidget
|
|
defaultButton</programlisting>
|
|
<para>The <symbol role="Variable">textWidget</symbol> parameter specifies
|
|
the widget to be configured to catch the Return key and force the focus to
|
|
move to the next text widget (as indicated by the <symbol role="Variable">nextTextWidget</symbol> parameter). The <symbol role="Variable">formWidget</symbol> parameter specifies the form containing the default button and
|
|
should be the parent of the two text widgets. The <symbol role="Variable">defaultButton</symbol> parameter indicates which component is to be treated
|
|
as the default button within the form widget.</para>
|
|
<para>Examples:</para>
|
|
<programlisting>DtkshSetReturnKeyControls $TEXT1 $TEXT2 $FORM $OK
|
|
DtkshSetReturnKeyControls $TEXT2 $TEXT3 $FORM $OK</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.4">
|
|
<title>DtkshUnder, DtkshOver, DtkshRightOf, and DtkshLeftOf<indexterm><primary>DtkshUnder</primary></indexterm><indexterm><primary>DtkshOver</primary></indexterm><indexterm>
|
|
<primary>DtkshRightOf</primary></indexterm><indexterm><primary>DtkshLeftOf</primary></indexterm></title>
|
|
<para>These convenience functions simplify the specification of certain classes
|
|
of form constraints. They provide a way of attaching a component to one
|
|
edge of another component. They are used when constructing the resource
|
|
list for a widget. This behavior is accomplished using the <filename>ATTACH_WIDGET</filename> constraint.</para>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshUnder widgetId [offset]
|
|
DtkshOver widgetId [offset]
|
|
DtkshRightOf widgetId [offset]
|
|
DtkshLeftOf widgetId [offset]</programlisting>
|
|
<para>The <symbol role="Variable">widgetId</symbol> parameter specifies the
|
|
widget to which the current component is to be attached. The <symbol role="Variable">offset</symbol> value is optional and defaults to 0 if not specified.</para>
|
|
<para>Example:</para>
|
|
<programlisting>XtCreateManagedWidget BUTTON4 button4 XmPushButton $FORM \
|
|
labelString:“Exit“ \
|
|
$(DtkshUnder $BUTTON2) \
|
|
$(DtkshRightOf $BUTTON3)</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.5">
|
|
<title>DtkshFloatRight, DtkshFloatLeft, DtkshFloatTop, and DtkshFloatBottom<indexterm>
|
|
<primary>DtkshFloatRight</primary></indexterm><indexterm><primary>DtkshFloatLeft</primary></indexterm><indexterm><primary>DtkshFloatTop</primary></indexterm><indexterm>
|
|
<primary>DtkshFloatBottom</primary></indexterm></title>
|
|
<para>These convenience functions simplify the specification of certain classes
|
|
of form constraints. They provide a way of positioning a component, independent
|
|
of the other components within the form. As the form grows or shrinks, the
|
|
component maintains its relative position within the form. The component
|
|
may still grow or shrink, depending upon the other form constraints specified
|
|
for the component. This behavior is accomplished using the <filename>ATTACH_POSITION</filename> constraint.</para>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshFloatRight [position]
|
|
DtkshFloatLeft [position]
|
|
DtkshFloatTop [position]
|
|
DtkshFloatBottom [position]</programlisting>
|
|
<para>The optional <symbol role="Variable">position</symbol> parameter specifies
|
|
the relative position to which the indicated edge of the component is positioned.
|
|
The <symbol role="Variable">position</symbol> value is optional and defaults
|
|
to 0 if one is not specified.</para>
|
|
<para>Example:</para>
|
|
<programlisting>XtCreateManagedWidget BUTTON1 button1 XmPushButton $FORM \
|
|
labelString:“Ok“ \
|
|
$(DtkshUnder $SEPARATOR) \
|
|
$(DtkshFloatLeft 10) \
|
|
$(DtkshFloatRight 40)</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.6">
|
|
<title>DtkshAnchorRight, DtkshAnchorLeft, DtkshAnchorTop, and DtkshAnchorBottom<indexterm>
|
|
<primary>DtkshAnchorRight</primary></indexterm><indexterm><primary>DtkshAnchorLeft</primary></indexterm><indexterm><primary>DtkshAnchorTop</primary></indexterm><indexterm>
|
|
<primary>DtkshAnchorBottom</primary></indexterm></title>
|
|
<para>These convenience functions simplify the specification of certain classes
|
|
of form constraints. They provide a way of attaching a component to one
|
|
of the edges of a form widget in such a way that, as the form grows or shrinks,
|
|
the component's position does not change. However, depending upon the other
|
|
form constraints set on this component, it may still grow or shrink in size.
|
|
This behavior is accomplished using the <filename>ATTACH_FORM</filename>
|
|
constraint.</para>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshAnchorRight [offset]
|
|
DtkshAnchorLeft [offset]
|
|
DtkshAnchorTop [offset]
|
|
DtkshAnchorBottom [offset]</programlisting>
|
|
<para>The optional <symbol role="Variable">offset</symbol> parameter specifies
|
|
how far from the edge of the form widget the component should be positioned.
|
|
If an offset is not specified, then 0 is used.</para>
|
|
<para>Example:</para>
|
|
<programlisting>XtCreateManagedWidget BUTTON1 button1 XmPushButton $FORM \
|
|
labelString:“Ok“ \
|
|
$(DtkshUnder $SEPARATOR) \
|
|
$(DtkshAnchorLeft 10) \
|
|
$(DtkshAnchorBottom 10)</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.7">
|
|
<title>DtkshSpanWidth and DtkshSpanHeight<indexterm><primary>DtkshSpanWidth</primary></indexterm><indexterm><primary>DtkshSpanHeight</primary></indexterm></title>
|
|
<para>These convenience functions simplify the specification of certain classes
|
|
of form constraints. They provide a way of configuring a component so that
|
|
it spans either the full height or width of the form widget. This behavior
|
|
is accomplished by attaching two edges of the component (top and bottom for
|
|
<command>DtSpanHeight</command>, and left and right for <command>DtSpanWidth</command>) to the form widget. The component typically resizes whenever
|
|
the form widget is resized. The <filename>ATTACH_FORM</filename> constraint
|
|
is used for all attachments.</para>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshSpanWidth [leftOffset rightOffset]
|
|
DtkshSpanHeight [topOffset bottomOffset]</programlisting>
|
|
<para>The optional <symbol role="Variable">offset</symbol> parameters specify
|
|
how far from the edges of the form widget the component should be positioned.
|
|
If an offset is not specified, then 0 is used.</para>
|
|
<para>Example:</para>
|
|
<programlisting>XtCreateManagedWidget SEP sep XmSeparator $FORM \
|
|
$(DtkshSpanWidth 1 1)</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.8">
|
|
<title>DtkshDisplayInformationDialog, DtkshDisplayQuestionDialog, DtDisplayWarningDialog, DtkshDisplayWorkingDialog, and DtkshDisplayErrorDialog<indexterm><primary>DtkshDisplayInformationDialog</primary></indexterm><indexterm><primary>DtkshDisplayQuestionDialog</primary></indexterm><indexterm><primary>DtDisplayWarningDialog</primary>
|
|
</indexterm><indexterm><primary>DtkshDisplayWorkingDialog</primary></indexterm><indexterm>
|
|
<primary>DtkshDisplayErrorDialog</primary></indexterm></title>
|
|
<para>These convenience functions create a single instance of each of the
|
|
Motif feedback dialogs. If an instance of the requested type of dialog already
|
|
exists, then it is reused. The parent of the dialog is obtained from the
|
|
environment variable <filename>$TOPLEVEL</filename>, which should be set
|
|
by the calling shell script, and then should not be changed. The handle
|
|
for the requested dialog is returned in one of the following environment
|
|
variables:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><filename>_DTKSH_ERROR_DIALOG_HANDLE</filename></para>
|
|
</listitem><listitem><para><filename>_DTKSH_QUESTION_DIALOG_HANDLE</filename></para>
|
|
</listitem><listitem><para><filename>_DTKSH_WORKING_DIALOG_HANDLE</filename></para>
|
|
</listitem><listitem><para><filename>_DTKSH_WARNING_DIALOG_HANDLE</filename></para>
|
|
</listitem><listitem><para><filename>_DTKSH_INFORMATION_DIALOG_HANDLE</filename></para>
|
|
</listitem></itemizedlist>
|
|
<note>
|
|
<para>If you are attaching your own callbacks to the dialog buttons, do not
|
|
destroy the dialog when you are done with it. Unmanage the dialog, so that
|
|
it can be used again at a later time. If it is necessary to destroy the
|
|
dialog, then be sure to clear the associated environment variable so the
|
|
convenience function does not attempt to reuse the dialog.</para>
|
|
</note>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshDisplay<<symbol role="Variable">name</symbol>>Dialog title message [okCallback closeCallback
|
|
helpCallback dialogStyle]</programlisting>
|
|
<para>The Ok button is always managed, and by default unmanages the dialog.
|
|
The Cancel and Help buttons are only managed when a callback is supplied
|
|
for them. The <symbol role="Variable">dialogStyle</symbol> parameter accepts
|
|
any of the standard resource settings supported by the associated bulletin
|
|
board resource.</para>
|
|
<para>Example:</para>
|
|
<programlisting>DtkshDisplayErrorDialog “Read Error“ “Unable to read the file“
|
|
“OkCallback“ \
|
|
“CancelCallback“ ““ DIALOG_PRIMARY_APPLICATION_MODAL
|
|
</programlisting>
|
|
</sect1>
|
|
<sect1 id="DKSUG.convf.div.9">
|
|
<title>DtkshDisplayQuickHelpDialog and DtkshDisplayHelpDialog<indexterm><primary>DtkshDisplayQuickHelpDialog</primary></indexterm><indexterm><primary>DtkshDisplayHelpDialog</primary></indexterm></title>
|
|
<para>These convenience functions create a single instance of each of the
|
|
help dialogs. If an instance of the requested type of help dialog already
|
|
exists, then it is reused. The parent of the dialog is obtained from the
|
|
environment variable <filename>$TOPLEVEL</filename>, which should be set
|
|
by the calling shell script, and then should not be changed. The handle
|
|
for the requested dialog is returned in one of the following environment
|
|
variables:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><filename>_DTKSH_HELP_DIALOG_HANDLE</filename></para>
|
|
</listitem><listitem><para><filename>_DTKSH_QUICK_HELP_DIALOG_HANDLE</filename></para>
|
|
</listitem></itemizedlist>
|
|
<note>
|
|
<para>If it is necessary to destroy a help dialog, then be sure to clear
|
|
the associated environment variable so that the convenience function does
|
|
not attempt to reuse the dialog.</para>
|
|
</note>
|
|
<para>Usage:</para>
|
|
<programlisting>DtkshDisplay*HelpDialog title helpType helpInformation [locationId]
|
|
</programlisting>
|
|
<para>The meaning of the parameters is dependent upon the value specified
|
|
for the <symbol role="Variable">helpType</symbol> parameter. Their meanings
|
|
are:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><symbol role="Variable">helpType</symbol> = <filename>HELP_TYPE_TOPIC</filename></para>
|
|
<itemizedlist remap="Bullet2"><listitem><para><symbol role="Variable">helpInformation</symbol> = help volume name</para>
|
|
</listitem><listitem><para><symbol role="Variable">locationId</symbol> = help
|
|
topic location ID</para>
|
|
</listitem></itemizedlist>
|
|
</listitem><listitem><para><symbol role="Variable">helpType</symbol> = <filename>HELP_TYPE_STRING</filename></para>
|
|
<itemizedlist remap="Bullet2"><listitem><para><symbol role="Variable">helpInformation</symbol> = help string</para>
|
|
</listitem><listitem><para><symbol role="Variable">locationId</symbol> = <not
|
|
used></para>
|
|
</listitem></itemizedlist>
|
|
</listitem><listitem><para><symbol role="Variable">helpType</symbol> = <filename>HELP_TYPE_DYNAMIC_STRING</filename></para>
|
|
<itemizedlist remap="Bullet2"><listitem><para><symbol role="Variable">helpInformation</symbol> = help string</para>
|
|
</listitem><listitem><para><symbol role="Variable">locationId</symbol> = <not
|
|
used></para>
|
|
</listitem></itemizedlist>
|
|
</listitem><listitem><para><symbol role="Variable">helpType</symbol> = <filename>HELP_TYPE_MAN_PAGE</filename></para>
|
|
<itemizedlist remap="Bullet2"><listitem><para><symbol role="Variable">helpInformation</symbol> = manual page name</para>
|
|
</listitem><listitem><para><symbol role="Variable">locationId</symbol> = <not
|
|
used></para>
|
|
</listitem></itemizedlist>
|
|
</listitem><listitem><para><symbol role="Variable">helpType</symbol> = <filename>HELP_TYPE_FILE</filename></para>
|
|
<itemizedlist remap="Bullet2"><listitem><para><symbol role="Variable">helpInformation</symbol> = help file name</para>
|
|
</listitem><listitem><para><symbol role="Variable">locationId</symbol> =
|
|
<not used></para>
|
|
</listitem></itemizedlist>
|
|
</listitem></itemizedlist>
|
|
<para>Example:</para>
|
|
<programlisting>DtkshDisplayHelpDialog “Help On Dtksh“ HELP_TYPE_FILE
|
|
“helpFileName“</programlisting>
|
|
</sect1>
|
|
</appendix>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
|
|
<?Pub Caret>
|
|
<?Pub *0000017940>
|