debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import of the CDE 2.1.30 sources from the Open Group.

Browse Source
This commit is contained in:
Peter Howkins
2012-03-10 18:21:40 +00:00
commit 83b6996daa
18978 changed files with 3945623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
cde/doc/C/guides/dtkshGuide/BEntity.sgm Normal file
View File

@@ -0,0 +1,19 @@
<!-- $XConsortium: BEntity.sgm /main/5 1996/06/19 16:03:14 drk $ -->
<!ENTITY DKSUG.scr1.fig.1 SYSTEM "./dtkshGuide/graphics/dttest1.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.1 SYSTEM "./dtkshGuide/graphics/findwin.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.2 SYSTEM "./dtkshGuide/graphics/finderr.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.3 SYSTEM "./dtkshGuide/graphics/findterm.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.4 SYSTEM "./dtkshGuide/graphics/labfindw.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.5 SYSTEM "./dtkshGuide/graphics/area1.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.6 SYSTEM "./dtkshGuide/graphics/area2.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.7 SYSTEM "./dtkshGuide/graphics/area3.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.8 SYSTEM "./dtkshGuide/graphics/area4.tif" NDATA TIFF>

3
cde/doc/C/guides/dtkshGuide/Title.tmpl Normal file
View File

@@ -0,0 +1,3 @@
/* $XConsortium: Title.tmpl /main/2 1996/06/19 16:03:17 drk $ */
/* TOC title, only what's between quotes should be modified. */
title = "Desktop KornShell User's Guide"

59
cde/doc/C/guides/dtkshGuide/adbook.sgm Normal file
View File

@@ -0,0 +1,59 @@
<!-- $XConsortium: adbook.sgm /main/7 1996/07/13 15:44:42 rws $ -->
<!DOCTYPE DocBook PUBLIC "-//HaL and O'Reilly//DTD DocBook V2.2.1//EN" [
<!ENTITY DKSUG.scr1.fig.1 SYSTEM "./graphics/dttest1.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.1 SYSTEM "./graphics/findwin.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.2 SYSTEM "./graphics/finderr.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.3 SYSTEM "./graphics/findterm.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.4 SYSTEM "./graphics/labfindw.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.5 SYSTEM "./graphics/area1.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.6 SYSTEM "./graphics/area2.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.7 SYSTEM "./graphics/area3.tif" NDATA TIFF>
<!ENTITY DKSUG.scr2.fig.8 SYSTEM "./graphics/area4.tif" NDATA TIFF>
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY Pref SYSTEM "./preface.sgm">
<!ENTITY Intro SYSTEM "./ch01.sgm">
<!ENTITY scr1 SYSTEM "./ch02.sgm">
<!ENTITY adv SYSTEM "./ch03.sgm">
<!ENTITY scr2 SYSTEM "./ch04.sgm">
<!ENTITY cmds SYSTEM "./appa.sgm">
<!ENTITY convf SYSTEM "./appb.sgm">
<!ENTITY finds SYSTEM "./appc.sgm">
]>
<!-- ____________________________________________________________________________ -->
<DocBook>
<Book>
<Title>Common Desktop Environment: Desktop KornShell User's Guide</Title>
&Pref;
&Intro;
&scr1;
&adv;
&scr2;
&cmds;
&convf;
&finds;
</Book>
</DocBook>

1148
cde/doc/C/guides/dtkshGuide/appa.sgm Normal file
View File

File diff suppressed because it is too large Load Diff

260
cde/doc/C/guides/dtkshGuide/appb.sgm Normal file
View File

@@ -0,0 +1,260 @@
<!-- $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:&ldquo;Exit&ldquo; \
$(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:&ldquo;Ok&ldquo; \
$(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:&ldquo;Ok&ldquo; \
$(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&lt;<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 &ldquo;Read Error&ldquo; &ldquo;Unable to read the file&ldquo;
&ldquo;OkCallback&ldquo; \
&ldquo;CancelCallback&ldquo; &ldquo;&ldquo; 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> = &lt;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> = &lt;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> = &lt;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> =
&lt;not used></para>
</listitem></itemizedlist>
</listitem></itemizedlist>
<para>Example:</para>
<programlisting>DtkshDisplayHelpDialog &ldquo;Help On Dtksh&ldquo; HELP_TYPE_FILE
&ldquo;helpFileName&ldquo;</programlisting>
</sect1>
</appendix>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub Caret>
<?Pub *0000017940>

404
cde/doc/C/guides/dtkshGuide/appc.sgm Normal file
View File

@@ -0,0 +1,404 @@
<!-- $XConsortium: appc.sgm /main/7 1996/09/08 19:45:21 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.finds.div.1">
<title>The script_find Script</title>
<para>This appendix contains the complete listing of <filename>script_find</filename> described in Chapter 4, &ldquo;A Complex Script.&rdquo; The
script executes a second script called <filename>Find.sticky</filename>,
which is listed after<indexterm><primary>script_find</primary></indexterm> <filename>script_find</filename>. There is also a file called <filename>Find.help</filename>,
which is a text file accessed when the user clicks the Help button on the
main script window. See Chapter 4 for more information on this script.
</para>
<sect1 id="DKSUG.finds.div.2">
<title>Listing for script_find</title>
<programlisting>#! /usr/dt/bin/dtksh
set -u
. /usr/dt/lib/dtksh/DtFuncs.dtsh
#
# This sample shell script provides a graphical interface to the
# `find' command. Each time it is executed, it will attempt to
# restore the dialog to the last set of values entered by the user.
# When the `find' command is initiated, the output will be displayed
# in a dtterm window.
#
#
# Post an# error dialog. The main application window is disabled
# until the error dialog is unposted. The message to be displayed
# in the # error dialog is passed in as $1
#
PostErrorDialog()
{
DtDisplayErrorDialog &ldquo;Find Error&rdquo; &ldquo;$1&rdquo; \
DIALOG_PRIMARY_APPLICATION_MODAL
}
#
# This is both the `Ok' and the `Apply' callback; in the case of the
# `Ok' callback, it unposts the main application window, and then
# exits, if the dialog contains valid information. For both `Ok' and
# `Apply', the set of search directories is first validated; if any
# of the paths are not valid, then an error dialog is posted.
# Otherwise, the `find' process is started in a terminal window.
#
OkCallback()
{
RetrieveAndSaveCurrentValues
if [ &ldquo;$SD_VAL&rdquo; = &ldquo;&ldquo; ]; then
PostErrorDialog &ldquo;You must specify a directory to search&rdquo;
else
for i in $SD_VAL; do
if [ ! -d $i ]; then
MSG=&rdquo;The following search directory does not exist:
$i&rdquo;
PostErrorDialog &ldquo;$MSG&rdquo;
return 1
fi
done
if [ $CB_WIDGET = $OK ]; then
XtPopdown $TOPLEVEL
fi
CMD=&rdquo;/bin/find $SD_VAL&rdquo;
if [ ! &ldquo;$FNP_VAL&rdquo; = &ldquo;&ldquo; ]; then
CMD=$CMD&rdquo; -name $FNP_VAL&rdquo;
fi
if ! $(XmToggleButtonGetState $T1); then
CMD=$CMD&rdquo; -xdev&rdquo;
fi
if $(XmToggleButtonGetState $T3); then
CMD=$CMD&rdquo; -hidden&rdquo;
fi
if $(XmToggleButtonGetState $T4); then
CMD=$CMD&rdquo; -follow&rdquo;
fi
if $(XmToggleButtonGetState $T5); then
CMD=$CMD&rdquo; -depth&rdquo;
fi
case $FSTYPE_VAL in
$NFS) CMD=$CMD&rdquo; -fsonly nfs&rdquo; ;;
$CDFS) CMD=$CMD&rdquo; -fsonly cdfs&rdquo; ;;
$HFS) CMD=$CMD&rdquo; -fsonly hfs&rdquo; ;;
*) ;;
esac
case $FILETYPE_VAL in
$REGULAR) CMD=$CMD&rdquo; -type f&rdquo; ;;
$DIRECTORY) CMD=$CMD&rdquo; -type d&rdquo; ;;
$BLOCK) CMD=$CMD&rdquo; -type b&rdquo; ;;
$CHAR) CMD=$CMD&rdquo; -type c&rdquo; ;;
$FIFO) CMD=$CMD&rdquo; -type p&rdquo; ;;
$SYMLINK) CMD=$CMD&rdquo; -type l&rdquo; ;;
$SOCKET) CMD=$CMD&rdquo; -type s&rdquo; ;;
$NET) CMD=$CMD&rdquo; -type n&rdquo; ;;
$MOUNT) CMD=$CMD&rdquo; -type M&rdquo; ;;
$HIDDEN) CMD=$CMD&rdquo; -type H&rdquo; ;;
*) ;;
esac
if $(XmToggleButtonGetState $T2); then
CMD=$CMD&rdquo; -print&rdquo;
fi
/usr/dt/bin/dtterm -title &ldquo;Find A File&rdquo; -e /usr/dt/bin/dtexec
-open -1 $CMD &amp;
if [ $CB_WIDGET = $OK ]; then
exit 0
fi
fi
}
#
# This function attempts to load in the previous dialog values.
# Each line read from the file is then interpreted as a ksh command.
#
LoadStickyValues()
{
if [ -r &ldquo;./Find.sticky&rdquo; ]; then
exec 6&lt; &ldquo;./Find.sticky&rdquo;
XtAddInput FID 6 &ldquo;EvalCmd&rdquo;
fi
}
#
# This function is invoked for each line in the `sticky' values file.
# It will evalutate each line as a dtksh command.
#
EvalCmd()
{
if [ ${#INPUT_LINE} -gt 0 ]; then
eval &ldquo;$INPUT_LINE&rdquo;
fi
if [ &ldquo;$INPUT_EOF&rdquo; = `true' ]; then
XtRemoveInput $INPUT_ID
eval exec $INPUT_SOURCE'&lt;&amp;-'
fi
}
#
# This function retrieves the current values, and then saves them
# off into a file, so that they can be restored the next time the
# dialog is displayed. It is called anytime the user selects either
# the &ldquo;Ok&rdquo; or &ldquo;Apply&rdquo; buttons.
#
RetrieveAndSaveCurrentValues()
{
XmTextGetString SD_VAL $SD
XmTextGetString FNP_VAL $FNP
XtGetValues $FSTYPE menuHistory:FSTYPE_VAL
XtGetValues $FILETYPE menuHistory:FILETYPE_VAL
exec 3> &ldquo;./Find.sticky&rdquo;
if [ ! &ldquo;$SD_VAL&rdquo; = &ldquo;&ldquo; ]; then
print -u 3 &ldquo;XmTextSetString \$SD \&rdquo;$SD_VAL\&rdquo;&rdquo;
print -u 3 &ldquo;XmTextFieldSetInsertionPosition \$SD ${#SD_VAL}&rdquo;
fi
if [ ! &ldquo;$FNP_VAL&rdquo; = &ldquo;&ldquo; ]; then
print -u 3 &ldquo;XmTextSetString \$FNP \&rdquo;$FNP_VAL\&rdquo;&rdquo;
print -u 3 &ldquo;XmTextFieldSetInsertionPosition \$FNP ${#FNP_VAL}&rdquo;
fi
case $FSTYPE_VAL in
$NFS) FST=&rdquo;\$NFS&rdquo; ;;
$CDFS) FST=&rdquo;\$CDFS&rdquo; ;;
$HFS) FST=&rdquo;\$HFS&rdquo; ;;
*) FST=&rdquo;\$NODIR&rdquo; ;;
esac
print -u 3 &ldquo;XtSetValues \$FSTYPE menuHistory:$FST&rdquo;
case $FILETYPE_VAL in
$REGULAR) FT=&rdquo;\$REGULAR&rdquo; ;;
$DIRECTORY) FT=&rdquo;\$DIRECTORY&rdquo; ;;
$BLOCK) FT=&rdquo;\$BLOCK&rdquo; ;;
$CHAR) FT=&rdquo;\$CHAR&rdquo; ;;
$FIFO) FT=&rdquo;\$FIFO&rdquo; ;;
$SYMLINK) FT=&rdquo;\$SYMLINK&rdquo; ;;
$SOCKET) FT=&rdquo;\$SOCKET&rdquo; ;;
$NET) FT=&rdquo;\$NET&rdquo; ;;
$MOUNT) FT=&rdquo;\$MOUNT&rdquo; ;;
$HIDDEN) FT=&rdquo;\$HIDDEN&rdquo; ;;
*) FT=&rdquo;\$NOTYPE&rdquo; ;;
esac
print -u 3 &ldquo;XtSetValues \$FILETYPE menuHistory:$FT&rdquo;
if $(XmToggleButtonGetState $T1); then
print -u 3 &ldquo;XmToggleButtonSetState \$T1 true false&rdquo;
fi
if $(XmToggleButtonGetState $T2); then
print -u 3 &ldquo;XmToggleButtonSetState \$T2 true false&rdquo;
fi
if $(XmToggleButtonGetState $T3); then
print -u 3 &ldquo;XmToggleButtonSetState \$T3 true false&rdquo;
fi
if $(XmToggleButtonGetState $T4); then
print -u 3 &ldquo;XmToggleButtonSetState \$T4 true false&rdquo;
fi
if $(XmToggleButtonGetState $T5); then
print -u 3 &ldquo;XmToggleButtonSetState \$T5 true false&rdquo;
fi
exec 3&lt;&amp;-
}
################ Create the Main UI ####################
set -f
XtInitialize TOPLEVEL find Dtksh $0 &ldquo;${@:-}&rdquo;
XtSetValues $TOPLEVEL title:&rdquo;Find Files&rdquo;
XtCreateManagedWidget FORM form XmForm $TOPLEVEL
XtCreateManagedWidget SDLABEL sdlabel XmLabel $FORM \
labelString:&rdquo;Search Directory:&rdquo; \
$(DtkshAnchorTop 12) \
$(DtkshAnchorLeft 10)
XtCreateManagedWidget SD sd XmText $FORM \
columns:30 \
value:&rdquo;.&rdquo; \
$(DtkshAnchorTop 6) \
$(DtkshRightOf $SDLABEL 10) \
$(DtkshAnchorRight 10) \
navigationType:EXCLUSIVE_TAB_GROUP
XmTextFieldSetInsertionPosition $SD 1
XtCreateManagedWidget FNPLABEL fnpabel XmLabel $FORM \
labelString:&rdquo;Filename Pattern:&rdquo; \
$(DtkshUnder $SDLABEL 24) \
$(DtkshAnchorLeft 10)
XtCreateManagedWidget FNP fnp XmText $FORM \
columns:30 \
$(DtkshUnder $SD 8) \
$(DtkshRightOf $FNPLABEL 10) \
$(DtkshAnchorRight 10) \
navigationType:EXCLUSIVE_TAB_GROUP
XtCreateManagedWidget SEP sep XmSeparator $FORM \
separatorType:SINGLE_DASHED_LINE \
$(DtkshUnder $FNP 10) \
$(DtkshSpanWidth)
XtCreateManagedWidget RC rc XmRowColumn $FORM \
orientation:HORIZONTAL \
numColumns:3 \
packing:PACK_COLUMN \
$(DtkshUnder $SEP 10) \
$(DtkshSpanWidth 10 10) \
navigationType:EXCLUSIVE_TAB_GROUP
DtkshAddButtons -w $RC XmToggleButtonGadget \
T1 &ldquo;Cross Mount Points&rdquo; &ldquo;&ldquo;\
T2 &ldquo;Print Matching Filenames&rdquo; &ldquo;&ldquo;\
T3 &ldquo;Search Hidden Subdirectories&rdquo; &ldquo;&ldquo;\
T4 &ldquo;Follow Symbolic Links&rdquo; &ldquo;&ldquo;\
T5 &ldquo;Descend Subdirectories First&rdquo; &ldquo;&ldquo;
XtCreateManagedWidget SEP2 sep XmSeparator $FORM \
separatorType:SINGLE_DASHED_LINE \
$(DtkshUnder $RC 10) \
$(DtkshSpanWidth)
XmCreatePulldownMenu PANE $FORM pane
DtkshAddButtons -w $PANE XmPushButtonGadget \
NODIR &ldquo;no restrictions&rdquo; &ldquo;&ldquo;\
NFS &ldquo;nfs&rdquo; &ldquo;&ldquo;\
CDFS &ldquo;cdfs&rdquo; &ldquo;&ldquo;\
HFS &ldquo;hfs&rdquo; &ldquo;&ldquo;
XmCreateOptionMenu FSTYPE $FORM fstype \
labelString:&rdquo;Restrict Search To File System Type:&rdquo; \
menuHistory:$NODIR \
subMenuId:$PANE \
$(DtkshUnder $SEP2 20) \
$(DtkshSpanWidth 10 10) \
navigationType:EXCLUSIVE_TAB_GROUP
XtManageChild $FSTYPE
XmCreatePulldownMenu PANE2 $FORM pane2
DtkshAddButtons -w $PANE2 XmPushButtonGadget \
NOTYPE &ldquo;no restrictions&rdquo; &ldquo;&ldquo;\
REGULAR &ldquo;regular&rdquo; &ldquo;&ldquo;\
DIRECTORY &ldquo;directory&rdquo; &ldquo;&ldquo;\
BLOCK &ldquo;block special&rdquo; &ldquo;&ldquo;\
CHAR &ldquo;character special&rdquo; &ldquo;&ldquo;\
FIFO &ldquo;fifo&rdquo; &ldquo;&ldquo;\
SYMLINK &ldquo;symbolic link&rdquo; &ldquo;&ldquo;\
SOCKET &ldquo;socket&rdquo; &ldquo;&ldquo;\
NET &ldquo;network special&rdquo; &ldquo;&ldquo;\
MOUNT &ldquo;mount point&rdquo; &ldquo;&ldquo;\
HIDDEN &ldquo;hidden directory&rdquo; &ldquo;&ldquo;
XmCreateOptionMenu FILETYPE $FORM filetype \
labelString:&rdquo;Match Only Files Of Type:&rdquo; \
menuHistory:$NOTYPE \
subMenuId:$PANE2 \
$(DtkshUnder $FSTYPE 10) \
$(DtkshSpanWidth 10 10) \
navigationType:EXCLUSIVE_TAB_GROUP
XtManageChild $FILETYPE
XtSetValues $FILETYPE spacing:90
XtCreateManagedWidget SEP3 sep3 XmSeparator $FORM \
$(DtkshUnder $FILETYPE 10) \
$(DtkshSpanWidth)
XtCreateManagedWidget OK ok XmPushButton $FORM \
labelString:&rdquo;Ok&rdquo; \
$(DtkshUnder $SEP3 10) \
$(DtkshFloatLeft 4) \
$(DtkshFloatRight 24) \
$(DtkshAnchorBottom 10)
XtAddCallback $OK activateCallback &ldquo;OkCallback&rdquo;
XtCreateManagedWidget APPLY apply XmPushButton $FORM \
labelString:&rdquo;Apply&rdquo; \
$(DtkshUnder $SEP3 10) \
$(DtkshFloatLeft 28) \
$(DtkshFloatRight 48) \
$(DtkshAnchorBottom 10)
XtAddCallback $APPLY activateCallback &ldquo;OkCallback&rdquo;
XtCreateManagedWidget CLOSE close XmPushButton $FORM \
labelString:&rdquo;Close&rdquo; \
$(DtkshUnder $SEP3 10) \
$(DtkshFloatLeft 52) \
$(DtkshFloatRight 72) \
$(DtkshAnchorBottom 10)
XtAddCallback $CLOSE activateCallback &ldquo;exit 1&rdquo;
XtCreateManagedWidget HELP help XmPushButton $FORM \
labelString:&rdquo;Help&rdquo; \
$(DtkshUnder $SEP3 10) \
$(DtFloatLeft 76) \
$(DtkshFloatRight 96) \
$(DtkshAnchorBottom 10)
XtAddCallback $HELP activateCallback \
&ldquo;DtkshDisplayQuickHelpDialog `Using The Find Command'
HELP_TYPE_FILE \
`./Find.help' &ldquo;
XtSetValues $FORM \
initialFocus:$SD \
defaultButton:$OK \
cancelButton:$CLOSE \
navigationType:EXCLUSIVE_TAB_GROUP
DtkshSetReturnKeyControls $SD $FNP $FORM $OK
LoadStickyValues
XtRealizeWidget $TOPLEVEL
XtMainLoop</programlisting>
</sect1>
<sect1 id="DKSUG.finds.div.3">
<title>Find.sticky</title>
<para>The following script,<indexterm><primary>Find.sticky</primary></indexterm> <filename>Find.sticky</filename> is executed by <filename>script_find</filename>. <filename>Find.sticky</filename> remembers the file and directory names used in the
most recent execution of <filename>script_find</filename>.</para>
<programlisting>XmTextSetString $SD &ldquo;/users/dlm&rdquo;
XmTextFieldSetInsertionPosition $SD 10
XmTextSetString $FNP &ldquo;elmbug&rdquo;
XmTextFieldSetInsertionPosition $FNP 6
XtSetValues $FSTYPE menuHistory:$NODIR
XtSetValues $FILETYPE menuHistory:$DIRECTORY
XmToggleButtonSetState $T1 true false
XmToggleButtonSetState $T2 true false</programlisting>
</sect1>
<sect1 id="DKSUG.finds.div.4">
<title>Find.help</title>
<para><filename>Find.help</filename> is a text file that is displayed on screen
when the user clicks the Help button in the main <filename>script_find</filename>
window.</para>
<programlisting>This dialog presents a graphical interface to the
UNIX `find' command. The only required field is
the name of the directory to be searched;
all other fields are optional. Once the fields have
been set to the desired values, you can use the
`Ok' or `Apply' button to initiate the find operation.
The results of the find operation are displayed
in a dtterm terminal window.</programlisting>
</sect1>
</appendix>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub Caret>
<?Pub *0000015484>

66
cde/doc/C/guides/dtkshGuide/book.sgm Normal file
View File

@@ -0,0 +1,66 @@
<!-- $XConsortium: book.sgm /main/5 1996/07/13 15:44:47 rws $ -->
<!DOCTYPE Book PUBLIC "-//HaL and O'Reilly//DTD DocBook//EN" [
<!ENTITY % ISOpublishing PUBLIC "ISO 8879-1986//ENTITIES Publishing//EN">
%ISOpublishing;
<!ENTITY % ISOnumeric PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN">
%ISOnumeric;
<!ENTITY % ISOdiacritical PUBLIC "ISO 8879-1986//ENTITIES Diacritical Marks//EN">
%ISOdiacritical;
<!ENTITY % ISOgeneraltech PUBLIC "ISO 8879-1986//ENTITIES General Technical//EN">
%ISOgeneraltech;
<!ENTITY % ISOalatin1 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN">
%ISOalatin1;
<!ENTITY % ISOalatin2 PUBLIC "ISO 8879-1986//ENTITIES Added Latin 2//EN">
%ISOalatin2;
<!ENTITY % ISOgreek PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN">
%ISOgreek;
<!ENTITY % ISOboxandline PUBLIC "ISO 8879-1986//ENTITIES Box and Line Drawing//EN">
%ISOboxandline;
<!ENTITY % BEntities SYSTEM "./dtkshGuide/BEntity.sgm">
%BEntities;
<!ENTITY % local.notations "| XPM | XBM | XWD">
<!NOTATION XPM SYSTEM "XPM">
<!NOTATION XBM SYSTEM "XBM">
<!NOTATION XWD SYSTEM "XWD">
<!ENTITY Pref SYSTEM "./dtkshGuide/preface.sgm">
<!ENTITY Intro SYSTEM "./dtkshGuide/ch01.sgm">
<!ENTITY scr1 SYSTEM "./dtkshGuide/ch02.sgm">
<!ENTITY adv SYSTEM "./dtkshGuide/ch03.sgm">
<!ENTITY scr2 SYSTEM "./dtkshGuide/ch04.sgm">
<!ENTITY cmds SYSTEM "./dtkshGuide/appa.sgm">
<!ENTITY convf SYSTEM "./dtkshGuide/appb.sgm">
<!ENTITY finds SYSTEM "./dtkshGuide/appc.sgm">
]>
<!-- ____________________________________________________________________________ -->
<Book>
<Title>Common Desktop Environment: Desktop KornShell User's Guide</Title>
&Pref;
&Intro;
&scr1;
&adv;
&scr2;
&cmds;
&convf;
&finds;
</Book>

516
cde/doc/C/guides/dtkshGuide/ch01.sgm Normal file
View File

@@ -0,0 +1,516 @@
<!-- $XConsortium: ch01.sgm /main/7 1996/09/08 19:45: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="DKSUG.Intro.div.1">
<title id="DKSUG.Intro.mkr.1">Introduction to Desktop KornShell</title>
<para>Desktop KornShell(<command>ldtksh<indexterm><primary>dtksh</primary>
<secondary>definition</secondary></indexterm></command>) provides kshell scripts
with the means for easily accessing most of the existing Xt and Motif&trade;
functions. <command>dtksh</command> is based on <filename>ksh-93<indexterm>
<primary>dtksh</primary><secondary>relationshipt to ksh-93</secondary></indexterm><indexterm>
<primary>ksh-93</primary></indexterm></filename>, which provides a powerful
set of tools and commands for the shell programmer, and which supports the
standard set of kshell programming commands.</para>
<para><command>dtksh</command> supports all the features and commands provided
by <filename>ksh-93</filename>. In addition, <command>dtksh</command> supports
a large selection of the <command>libDt</command> functions, most of the
widget-related Motif functions, a large subset of the Xt Intrinsics functions,
and a small subset of the Xlib functions. All the supported functions are
listed in Appendix A.<indexterm><primary>supported functions</primary></indexterm><indexterm>
<primary>functions</primary><secondary>supported</secondary></indexterm></para>
<sect1 id="DKSUG.Intro.div.2">
<title>Using Desktop KornShell to Create Motif Applications</title>
<para>This section describes how to use <command>dtksh</command> to create<indexterm><primary>Motif applications</primary></indexterm>
Motif<indexterm>
<primary>applications, Motif</primary></indexterm> applications. To successfully
use <command>dtksh</command>, you should have experience with Xlib, the Xt
Intrinsics, the Motif widgets, and KornShell programming. It is also helpful
to know the C programming language. If you are not familiar with any of
these, you should refer to the appropriate documentation. Even if you are
familiar with these systems, you should have access to the applicable man
pages for reference.</para>
<para>In addition, your system should have these libraries:<indexterm><primary>required linbraries</primary></indexterm><indexterm><primary>libraries, required</primary></indexterm></para>
<itemizedlist remap="Bullet1"><listitem><para><command>libDtHelp</command></para>
</listitem><listitem><para><command>libDtSvc</command></para>
</listitem><listitem><para><command>libX11</command></para>
</listitem><listitem><para><command>libXm</command></para>
</listitem><listitem><para><command>libXt</command></para>
</listitem><listitem><para><command>libtt</command></para>
</listitem></itemizedlist>
<sect2 id="DKSUG.Intro.div.3">
<title>Resources<indexterm><primary>resources</primary></indexterm></title>
<para>Resources are widget variables that you use to define attributes such
as size, location, or color. Each widget usually has a combination of its
own resources, plus resources it inherits from higher level widgets. Xt
Intrinsics and Motif resource names consist of a prefix (<command>XtN</command>
or <command>XmN</command>) followed by the base name. The first letter of
the base name is <emphasis>always</emphasis> lowercase, and the first letter
of subsequent words within the base name is <emphasis>always</emphasis> uppercase.
The convention for resource names in <command>dtksh</command> scripts is
to delete the prefix and use the base name. Thus, the resource <command>XmNtopShadowColor</command> becomes <command>topShadowColor</command>.<indexterm>
<primary>XmNtopShadowColor</primary></indexterm><indexterm><primary>topShadowColor</primary></indexterm></para>
<para>Some Xt and Motif commands allow the shell script to pass in a variable
number of<indexterm><primary>parameters, variable number</primary></indexterm> parameters,
representing resource-value pairs. This is similar to the argument list passed
to the corresponding Xt or Motif C function. Examples include any of the
commands used to create a widget, plus the <command>XtSetValues</command>
command. In <command>dtksh</command>, resources are specified by a string
with the following syntax:</para>
<programlisting>resource:<symbol role="Variable">value</symbol></programlisting>
<para>where <symbol role="Variable">resource</symbol> is the name of the resource
and <symbol role="Variable">value</symbol> is the value assigned to the resource.
<command>dtksh</command> automatically converts the <symbol role="Variable">value</symbol> string to an appropriate internal representation. For example:
</para>
<programlisting>XtSetValues $WIDGET height:100 width:200 resizePolicy:RESIZE_ANY
XmCreateLabel LABEL $PARENT myLabel labelString:&rdquo;Close Dialog&rdquo;
</programlisting>
<para>When you retrieve widget resource values using <command><indexterm>
<primary>XtGetValues</primary></indexterm>XtGetValues</command>, the return
value is placed in an environment variable. Thus, unlike the Xt Intrinsics,
the <command>dtksh</command> version of <command>XtGetValues</command> uses
a name:(environment) variable pair, rather than a name:value pair. For example:
</para>
<programlisting>XtGetValues $WIDGET height:HEIGHT resizePolicy:POLICY
sensitive:SENSITIVE
echo $HEIGHT
echo $POLICY
echo $SENSITIVE</programlisting>
<para>The preceding <command>dtksh</command> segment might produce this output:
</para>
<programlisting>100
RESIZE ANY
TRUE</programlisting>
<para>Certain types of resource values, including string tables and bit masks,
have special representation. For example, the List widget allows a string
table to be specified for both the <command>items</command> and <command>selectedItems</command> resources. In <command>dtksh</command>, a string
table is represented as a comma-separated list of strings, which is similar
to how Motif treats them. When a resource that returns a string table is
queried using <command>XtGetValues<indexterm><primary>XtGetValues</primary>
</indexterm></command>, the resulting value is a comma-separated set of strings.
</para>
<para>A resource that expects a bit mask value to be passed to it expects
the mask to be specified as a string composed of the various mask values
separated by the |(bar) character. When a resource that returns a bit mask
is queried, the return value is a string representing the enabled bits, separated
by the | character. For example, you could use the following command to set
the <command><indexterm><primary>mwmFunctions</primary></indexterm><indexterm>
<primary>VendorShell</primary></indexterm>mwmFunctions</command> resource
for the <command>VendorShell</command> widget class:</para>
<programlisting>XtSetValues mwmFunctions: MWM_FUNC_ALL|MWM_FUNC_RESIZE</programlisting>
</sect2>
<sect2 id="DKSUG.Intro.div.4">
<title>Unsupported Resources<indexterm><primary>unsupported resources</primary>
</indexterm><indexterm><primary>resource</primary><secondary>unsupported</secondary></indexterm></title>
<para><command>dtksh</command> supports most of the Motif resources. The
following lists unsupported resources. Resources with an * (asterisk) can
be specified at widget creation time by using <command><indexterm><primary>XtSetValues</primary></indexterm>XtSetValues</command>, but can't be retrieved
using <command><indexterm><primary>XtGetValues</primary></indexterm>XtGetValues</command>.</para>
<itemizedlist remap="Bullet1"><listitem><para>All widget and gadget Classes:
</para>
<itemizedlist remap="Bullet2"><listitem><para>Any fontlist resource *</para>
</listitem><listitem><para>Any pixmap resource *</para>
</listitem></itemizedlist>
</listitem><listitem><para>Composite:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>insertPosition</command></para>
</listitem><listitem><para><command>children</command></para>
</listitem></itemizedlist>
</listitem><listitem><para>Core:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>accelerators</command></para>
</listitem><listitem><para><command>translations</command> *</para>
</listitem><listitem><para><command>colormap</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>XmText</command>:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>selectionArray</command></para>
</listitem><listitem><para><command>selectionArrayCount</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>ApplicationShell</command>:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>argv</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>WMShell</command>:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>iconWindow</command></para>
</listitem><listitem><para><command>windowGroup</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>Shell</command>:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>createPopupChildrenProc</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>XmSelectionBox</command>:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>textAccelerators</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>Manager</command>, <command>Primitive</command>, and <command>Gadget</command> Subclasses:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>userData</command></para>
</listitem></itemizedlist>
</listitem><listitem><para><command>XmFileSelectionBox</command>:</para>
<itemizedlist remap="Bullet2"><listitem><para><command>dirSearchProc</command></para>
</listitem><listitem><para><command>fileSearchProc</command></para>
</listitem><listitem><para><command>qualifySearchDataProc</command></para>
</listitem></itemizedlist>
</listitem></itemizedlist>
</sect2>
<sect2 id="DKSUG.Intro.div.5">
<title>dtksh app-defaults File<indexterm><primary>app-defaults file</primary>
</indexterm></title>
<para>The <command>dtksh</command> <filename>app-defaults</filename> file,
named <command>Dtksh</command><indexterm><primary>Dtksh, app-defaults file</primary></indexterm>, is found in a location based on the following path
description:</para>
<programlisting>/usr/dt/app-defaults/&lt;LANG></programlisting>
<para>The only information contained in this <filename>app-defaults</filename>
file is the inclusion of the standard <command>Dt</command> base
<filename>app-defaults</filename> file. The following is a listing of the <command>dtksh</command> <filename>app-defaults</filename> file:</para>
<programlisting>#include &ldquo;Dt&ldquo;</programlisting>
<para>The file <command>Dt</command> is also located in <computeroutput>/usr/dt/app-defaults/&lt;LANG></computeroutput> and is shown in the following listing.</para>
<programlisting>*foregroundThreshold: 70
!###
!#
!# Help system specific resources
!#
!###
!#
!# Display Area Colors
!#
!# These resources set the colors for the display area (where
!# actual help text is displayed). The resources are complex
!# because they have to override the standard color resources
!# in all cases.
!#
*XmDialogShell.DtHelpDialog*DisplayArea.background: White
*XmDialogShell*XmDialogShell.DtHelpDialog*DisplayArea.background:
White
*XmDialogShell.DtHelpDialog*DisplayArea.foreground: Black
*XmDialogShell*XmDialogShell.DtHelpDialog*DisplayArea.foreground:
Black
!#
!# Menu Accelerators
!#
!# The following resources establish keyboard accelerators
!# for the most frequently accessed menu commands.
!#
*DtHelpDialogWidget*searchMenu.keyword.acceleratorText: Ctrl+I
*DtHelpDialogWidget*searchMenu.keyword.accelerator: Ctrl&lt;Key>i
*DtHelpDialogWidget*navigateMenu.backTrack.acceleratorText: Ctrl+B
*DtHelpDialogWidget*navigateMenu.backTrack.accelerator: Ctrl&lt;Key>b
*DtHelpDialogWidget*navigateMenu.homeTopic.acceleratorText: Ctrl+H
*DtHelpDialogWidget*navigateMenu.homeTopic.accelerator: Ctrl&lt;Key>h
*DtHelpDialogWidget*fileMenu.close.acceleratorText: Alt+F4
*DtHelpDialogWidget*fileMenu.close.accelerator: Alt&lt;Key>f4</programlisting>
</sect2>
<sect2 id="DKSUG.Intro.div.6">
<title>Variable Values<indexterm><primary>variable values</primary></indexterm></title>
<para>This section describes the types of values for some of the variables
in a <command>dtksh</command> <filename>app-defaults</filename> file.</para>
<sect3 id="DKSUG.Intro.div.7">
<title>Defined Values<indexterm><primary>Defined Values</primary></indexterm></title>
<para>The C bindings of the interfaces to X, Xt and Motif include many nonstring
values that are defined in header files. The general format of such values
consists of an <command>Xt</command> or <command>Xm</command> prefix followed
by a descriptive name. For example, one of the constraint values for a child
of a form widget is <filename>XmATTACH_FORM</filename>. Equivalent values
are specified in <command>dtksh</command> by dropping the prefix, just as
in a Motif defaults file:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>XmDIALOG_COMMAND_TEXT</filename>
becomes <filename>DIALOG_COMMAND_TEXT</filename></para>
</listitem><listitem><para><filename>XtATTACH_FORM</filename>
becomes <filename>ATTACH_FORM</filename></para>
</listitem></itemizedlist>
</sect3>
<sect3 id="DKSUG.Intro.div.8">
<title>Boolean Values<indexterm><primary>Boolean Values</primary></indexterm></title>
<para>You can specify a Boolean value as a parameter to a <command>dtksh</command>
command using the words True or False; case is not significant. A Boolean
result is returned as either True or False, using all lowercase letters.
</para>
</sect3>
</sect2>
<sect2 id="DKSUG.Intro.div.9">
<title>Return Values<indexterm><primary>Return Values</primary></indexterm></title>
<para>Graphical commands in <command>dtksh</command> fall into one of four
categories, based on the definition of the corresponding C function:</para>
<orderedlist><listitem><para>The function is void and returns no values.
Example: <filename>XtMapWidget()</filename></para>
</listitem><listitem><para>The function is void, but returns one or more values
through reference parameters. Example: <filename>XmGetColors()</filename></para>
</listitem><listitem><para>The function returns a non-Boolean value. Example:
<filename>XtCreateManagedWidget()</filename></para>
</listitem><listitem><para>The function returns a Boolean value. Example:
<filename>XtIsSensitive()</filename></para>
</listitem></orderedlist>
<sect3 id="DKSUG.Intro.div.10">
<title>Category 1<indexterm><primary>return value</primary><secondary>category
1</secondary></indexterm></title>
<para>A <command>dtksh</command><indexterm><primary>category 1</primary>
</indexterm> category 1 command follows the calling sequence of its corresponding
C function. The number and order of parameters can be determined by looking
at the standard documentation for the function. Example:</para>
<programlisting>XtMapWidget $FORM
</programlisting>
</sect3>
<sect3 id="DKSUG.Intro.div.11">
<title>Category 2<indexterm><primary>return value</primary><secondary>category
2</secondary></indexterm></title>
<para>A <command>dtksh</command><indexterm><primary>category 2</primary>
</indexterm> category 2 command also generally follows the calling sequence
of its corresponding C function. It returns a value in an environment variable,
instead of passing a pointer to a return variable. Example:</para>
<programlisting>XmGetColors $FORM $BG FOREGROUND TOPSHADOW BOTTOMSHADOW SELECT
echo &ldquo;Foreground color = &ldquo; $FOREGROUND</programlisting>
</sect3>
<sect3 id="DKSUG.Intro.div.12">
<title>Category 3<indexterm><primary>return value</primary><secondary>category
3</secondary></indexterm></title>
<para>A <command>dtksh</command><indexterm><primary>category 3</primary>
</indexterm> category 3 command differs slightly from its corresponding C
function. Where the C function returns its value as the value of the procedure
call, a <command>dtksh</command> command requires an additional parameter.
This parameter is the name of an environment variable into which the return
value is to be placed. It is always the first parameter. Example:
</para>
<programlisting>XmTextGetString TEXT_VALUE $TEXT_WIDGET
echo &ldquo;The value of the text field is &ldquo;$TEXT_VALUE</programlisting>
</sect3>
<sect3 id="DKSUG.Intro.div.13">
<title>Category 4<indexterm><primary>return value</primary><secondary>category
4</secondary></indexterm></title>
<para>A <command>dtksh</command><indexterm><primary>category 4</primary>
</indexterm> category 4 command returns a value that can be used in a conditional
expression just as in C. If the C function also returns values through reference
variables (as in category 2), the <command>dtksh</command> command also uses
variable names for the corresponding parameters. Example:</para>
<programlisting>if XmIsTraversable $PUSH_BUTTON; then
echo &ldquo;The pushbutton is traversable&rdquo;
else
echo &ldquo;The pushbutton is not traversable&rdquo;
fi</programlisting>
<para>Generally, the order and type of parameters passed to a command matches
those passed to the corresponding C function, except as noted for category
3 commands.</para>
</sect3>
</sect2>
<sect2 id="DKSUG.Intro.div.14">
<title>Immediate Return Value<indexterm><primary>return value</primary><secondary>immediate</secondary></indexterm><indexterm><primary>immediate return value</primary></indexterm></title>
<para>Many of the<indexterm><primary>category 3</primary></indexterm> category
3 commands return a single value using an environment variable specified
as the first parameter to the command (for these special commands, the first
parameter has the name <symbol role="Variable">variable</symbol>). If this
return value is immediately used in an expression, the special environment
variable &ldquo;-&ldquo; may be used in place of a variable name. When <command>dtksh</command> encounters &ldquo;-&ldquo; as the name of the environment
variable in which the return value is to be returned, it instead returns
the result as the value of the command. This allows the shell script to
embed the command call in another command call. This feature only works
for commands that return a single value, and the value is returned in the
first parameter. For example:</para>
<programlisting>XtDisplay DISPLAY $FORM
XSync $DISPLAY true</programlisting>
<para>can be replaced by the equivalent statement:</para>
<programlisting>XSync $(XtDisplay &ldquo;-&ldquo; $FORM) true</programlisting>
<para>The reference to <filename>$DISPLAY</filename> is replaced with the
value returned by the call to <command>XtDisplay</command>.</para>
<para>This capability is available for all category 3 commands except those
that create a widget, those that return more than a single value, and those
whose first parameter is not a named variable. Commands that do not accept
&ldquo;-&ldquo; as the environment variable name include the following:
</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>XtInitialize()</filename></para>
</listitem><listitem><para><filename>XtCreateApplicationShell()</filename></para>
</listitem><listitem><para><filename>XtCreatePopupShell()</filename></para>
</listitem><listitem><para><filename>XtCreateManagedWidget()</filename></para>
</listitem><listitem><para><filename>XtCreateWidget()</filename></para>
</listitem><listitem><para>All commands of the form:</para>
<programlisting>XmCreate...()</programlisting>
</listitem><listitem><para>Most commands of the form:</para>
<programlisting>tt_...()</programlisting>
</listitem></itemizedlist>
</sect2>
</sect1>
<sect1 id="DKSUG.Intro.div.15">
<title>Initializing the Xt Intrinsics<indexterm><primary>Xt Intrinsics</primary>
<secondary>initialize</secondary></indexterm><indexterm><primary>initialize
Xt Intrinsics</primary></indexterm></title>
<para>A <command>dtksh</command> script must first initialize the Xt Intrinsics
before it can call any of the Xlib, Xt, Motif, or <command>libDt</command>
commands. You accomplish this by invoking the <command><indexterm><primary>XtInitialize</primary></indexterm>XtInitialize</command> command, which returns
an application shell widget. As is true for all <command>dtksh</command>
commands that return a widget ID, <command>XtInitialize</command> returns
the widget ID in the environment variable that is the first argument. For
example, in:</para>
<programlisting>XtInitialize TOPLEVEL myShellName Dtksh $0 &ldquo;$@&rdquo;
</programlisting>
<para>the widget ID is returned in the environment variable <command>TOPLEVEL</command>.</para>
<para><command>dtksh</command> provides a default <filename>app-defaults</filename>
file, which is used if the call to <command>XtInitialize</command> specifies
an application class name of <command>Dtksh</command>. This
<filename>app-defaults</filename> file contains the standard set of <command>Dt</command>
application default values, so <command>dtksh</command> applications have
a consistent look with other <command>Dt</command> applications.</para>
<sect2 id="DKSUG.Intro.div.16">
<title>Creating Widgets<indexterm><primary>widget</primary><secondary>create</secondary></indexterm><indexterm><primary>create widget</primary></indexterm></title>
<para>There are several commands you can use to create widgets:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<colspec align="left" colwidth="235*">
<colspec align="left" colwidth="221*">
<tbody>
<row>
<entry align="left" valign="top"><para><command>XtCreateWidget</command><indexterm>
<primary>XtCreateWidget</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Creates an unmanaged widget.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>XtCreateManagedWidget</command><indexterm>
<primary>XtCreateManagedWidget</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Creates a managed widget.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>XtCreateApplicationShell</command><indexterm>
<primary>XtCreateApplicationShell</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Creates an application shell.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>XtCreatePopupShell</command><indexterm>
<primary>XtCreatePopupShell</primary></indexterm></para></entry>
<entry align="left" valign="top"><para>Creates a pop-up shell.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><command>XmCreate</command>&lt; <emphasis>widgettypes</emphasis>></para></entry>
<entry align="left" valign="top"><para>Creates an unmanaged widget.</para></entry>
</row></tbody></tgroup></informaltable>
<para>There is a specific format for each of these commands that you must
follow. For example, suppose you want to create an unmanaged push button
widget as a child of the top-level widget. You can use either <command>XtCreateWidget</command> or <command>XmCreatePushButton</command>. The formats
for these commands are:</para>
<itemizedlist remap="Bullet1"><listitem><para><computeroutput>XtCreateWidget</computeroutput> <emphasis>variable name widgetclass $parent [resource:value
...]</emphasis><indexterm><primary>XtCreateWidget</primary></indexterm></para>
</listitem><listitem><para><computeroutput>XmCreatePushButton</computeroutput> <emphasis>variable $parent name [resource:value ...]</emphasis><indexterm><primary>XmCreatePushButton</primary></indexterm></para>
</listitem></itemizedlist>
<para>The actual commands to create a push button widget are:</para>
<programlisting>XtCreateWidget BUTTON button XmPushButton $TOPLEVEL
XmCreatePushButton BUTTON $TOPLEVEL button</programlisting>
<para>Each of the preceeding commands do exactly the same thing: create an
unmanaged push button. Note that no resource values are set. Suppose that
you want the background color of the push button to be red, and the foreground
color to be black. You can set the values of these resources this way:</para>
<programlisting>XtCreateWidget BUTTON button XmPushButton $TOPLEVEL \
background:Red \
foreground:Black
XmCreatePushButton BUTTON $TOPLEVEL button\
background:Red \
foreground:Black</programlisting>
<para>All of the C functions that create a widget return a<indexterm><primary>widget</primary><secondary>handle</secondary></indexterm><indexterm><primary>handle</primary></indexterm> widget ID, or ID. The corresponding <command>dtksh</command> commands set an environment variable equal to the widget
ID. These are category 3 commands, so the first argument is the name of
the environment variable in which to return the widget ID. The widget ID
is an ASCII string used by <command>dtksh</command> to access the actual
widget pointer. Either of the following commands could be used to create
a new form widget; however, in each case the widget ID for the new form widget
is returned in the environment variable <command>FORM</command>:</para>
<itemizedlist remap="Bullet1"><listitem><para><command>XtCreateManagedWidget
FORM name XmForm $PARENT</command><indexterm><primary>XtCreateManagedWidget</primary></indexterm></para>
</listitem><listitem><para><command>XmCreateForm FORM $PARENT name</command><indexterm>
<primary>XmCreateForm</primary></indexterm></para>
</listitem></itemizedlist>
<para>After either of these commands, you can use <filename>$FORM</filename>
to reference the new form widget. For example, you could use this command
to create a label widget within the new form widget:</para>
<programlisting>XmCreateLabel LABEL $FORM name\
labelString:&rdquo;Hi Mom&rdquo; \
CH_FORM \
leftAttachment:ATTACH_FORM<indexterm><primary>XmCreateLabel</primary></indexterm></programlisting>
<note>
<para>There is a special widget ID called NULL, provided for cases where
a shell script may need to specify a NULL widget. For example, to disable
the <command>defaultButton</command> resource for a form widget, use the
command <command>X</command><command>tSetValues $FORM defaultButton:NULL</command></para>
</note>
</sect2>
</sect1>
<sect1 id="DKSUG.Intro.div.17">
<title>Using a Callback<indexterm><primary>callback</primary></indexterm></title>
<para>A callback is a function or procedure that is executed when an event
or combination of events occurs. For example, a callback is used to achieve
the desired result when a push button is &ldquo;pressed.&rdquo; It is
easy for a <command>dtksh</command> shell script to assign a command to be
activated whenever a particular callback is invoked for a widget. The command
could be as simple as a string of commands blocked together, or the name
of the shell function to invoke.</para>
<sect2 id="DKSUG.Intro.div.18">
<title>Registering a Callback<indexterm><primary>callback</primary><secondary>register</secondary></indexterm><indexterm><primary>register callback</primary>
</indexterm></title>
<para>An application registers a callback with a widget to specify a condition
in which it is interested and to specify what action should occur when that
condition occurs. The callback is registered using <command><indexterm>
<primary>XtAddCallback</primary></indexterm>XtAddCallback</command>. The
action can be any valid <command>dtksh</command> command. For example:</para>
<programlisting>XtAddCallback $WIDGET activateCallback &ldquo;ActivateProc&rdquo;
XtAddCallback $WIDGET activateCallback \
&ldquo;XtSetSensitive $BUTTON false&rdquo;
</programlisting>
</sect2>
<sect2 id="DKSUG.Intro.div.19">
<title>Passing Data to a Callback<indexterm><primary>callback</primary><secondary>pass data to</secondary></indexterm></title>
<para>A callback needs to be passed context information, so it can determine
what condition led to its call. For a C procedure, this information is typically
passed in a <command>callData</command> structure. For example, a scale
widget invoking a <command>valueChangedCallback</command> passes an instance
of the following structure in <command>callData</command>:</para>
<programlisting>typedef struct {
int reason;
XEvent event;
int value;
}XmScaleCallbackStruct;</programlisting>
<para>The C application's callback then does something like:</para>
<programlisting>if (scaleCallData->reason == XmCR_VALUE_CHANGED)
{
eventType = scaleCallData->event->type;
display = scaleCallData->event->xany.display;
}</programlisting>
<para>Similarly, when a callback is invoked in <command>dtksh</command>, the
following special environment variable is set up before the callback command
executes:</para>
<programlisting>CB_WIDGET</programlisting>
<para>This is set to the widget ID for the widget that is invoking the callback.
</para>
<programlisting>CB_CALL_DATA</programlisting>
<para>This is set to the address of the <command>callData</command> structure
passed by the widget to the callback.</para>
<para>The <filename><indexterm><primary>CB_CALL_DATA</primary></indexterm>CB_CALL_DATA</filename> environment variable represents a pointer to a structure, and
access to its fields uses a syntax similar to that of C. Nested environment
variables are defined, named the same as the fields of the structure (but
all in uppercase), and a dot is used to indicate containment of an element
in a structure. Thus, the previous C code to access the <command>callData</command> provided by the scale widget translates to:</para>
<programlisting>if [ ${CB_CALL_DATA.REASON} = &ldquo;CR_VALUE_CHANGED&rdquo; ]; then
eventType=${CB_CALL_DATA.EVENT.TYPE}
display=${CB_CALL_DATA.EVENT.XANY.DISPLAY}
fi</programlisting>
<para>The same is true of the event structure within the <command>callData</command> structure.</para>
<para>For most callback structures, the shell script is able to reference
any of the fields defined for the particular callback structure, using the
technique described earlier. In most cases, the shell script is not able
to alter the values of the fields within these structures. The exception
to this is the <command>XmTextVerifyCallbackStruct</command>, which is available
during the <command>losingFocusCallback</command>, the <command>modifyVerifyCallback</command> and the <command>motionVerifyCallback</command> for the text widget.
<command>dtksh</command> supports the modification of certain fields within
this structure, to the extent that it is supported by Motif. The following
fields within the callback structure are capable of being modified:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>CB_CALL_DATA.DOIT</filename></para>
</listitem><listitem><para><filename>CB_CALL_DATA.STARTPOS</filename></para>
</listitem><listitem><para><filename>CB_CALL_DATA.TEXT.PTR</filename></para>
</listitem><listitem><para><filename>CB_CALL_DATA.TEXT.LENGTH</filename></para>
</listitem><listitem><para><filename>CB_CALL_DATA.TEXT.FORMAT</filename></para>
</listitem></itemizedlist>
<para>This is an example of how one of these fields can be modified:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>CB_CALL_DATA.DOIT=&rdquo;false&rdquo;</filename></para>
</listitem><listitem><para><filename>CB_CALL_DATA.TEXT.PTR=&rdquo;*&rdquo;</filename></para>
</listitem><listitem><para><filename>CB_CALL_DATA.TEXT.LENGTH=1</filename></para>
</listitem></itemizedlist>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub Caret>
<?Pub *0000033871>

133
cde/doc/C/guides/dtkshGuide/ch02.sgm Normal file
View File

@@ -0,0 +1,133 @@
<!-- $XConsortium: ch02.sgm /main/7 1996/09/08 19:45:49 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="DKSUG.scr1.div.1">
<title>A Sample Script<indexterm><primary>script</primary><secondary>sample</secondary></indexterm><indexterm><primary>sample script</primary></indexterm></title>
<para>This chapter shows you how to use what you learned about <command>dtksh</command> in Chapter 1. The two simple scripts described here should give
you a good start at writing your own scripts.</para>
<sect1 id="DKSUG.scr1.div.2">
<title>Writing the Script<indexterm><primary>script</primary><secondary>writing</secondary></indexterm></title>
<para>This script creates a bulletin board widget within which a push button
widget is placed. The script is kept simple by not including any callbacks.
The second script includes a callback.</para>
<para>Here's the first script:</para>
<programlisting>#!/usr/dt/bin/dtksh
XtInitialize TOPLEVEL dttest1 Dtksh $0<indexterm><primary>XtInitialize</primary>
</indexterm>
XtSetValues $TOPLEVEL title:&ldquo;dttest1&rdquo;<indexterm><primary>XtSetValues</primary></indexterm>
XtCreateManagedWidget BBOARD bboard XmBulletinBoard $TOPLEVEL \
resizePolicy:RESIZE_NONE height:150 width:250\
background:SkyBlue<indexterm><primary>XtCreateManagedWidget</primary></indexterm>
XtCreateManagedWidget BUTTON pushbutton XmPushButton $BBOARD \<indexterm>
<primary>XtCreateManagedWidget</primary></indexterm>
background:goldenrod \
foreground:MidnightBlue \
labelString:&rdquo;Push Here&rdquo; \
height:30 width:100 x:75 y:60 shadowThickness:3
XtRealizeWidget $TOPLEVEL<indexterm><primary>XtRealizeWidget</primary></indexterm>XtMainLoop<indexterm>
<primary>XtMainLoop</primary></indexterm></programlisting>
<para>Figure 2-1 shows the window that the first script produces.</para>
<figure>
<title>Window from script dttest</title>
<graphic id="DKSUG.scr1.grph.1" entityref="DKSUG.scr1.fig.1"></graphic>
</figure>
<para>The first line of the script:</para>
<programlisting>#!/usr/dt/bin/dtksh</programlisting>
<para>tells the operating system that this script should be executed using
<filename>/usr/dt/bin/dtksh</filename> rather than the standard shell.</para>
<para>The next line initializes the Xt Intrinsics.<indexterm><primary>initialize</primary></indexterm></para>
<para>XtInitialize TOPLEVEL dttest1 Dtksh $0</para>
<para>The name of the<indexterm><primary>toplevel widget</primary></indexterm><indexterm>
<primary>widget</primary><secondary>toplevel</secondary></indexterm> top-level
widget is saved in the environment variable <filename>$TOPLEVEL</filename>,
the shell widget name is <filename>dttest1</filename>, the application class
name is <filename>Dtksh,</filename> and the application name is given by
the <command>dtksh</command> variable <filename>$0</filename>.</para>
<para>The next line sets the title resource to the name of the script.</para>
<programlisting>XtSetValues $TOPLEVEL title:&rdquo;dttest1&rdquo;</programlisting>
<para>Notice that there is no space between the colon after the resource name
(title) and its value. An error message appears if you have a space between
them.</para>
<para>The next four lines create a<indexterm><primary>bulletin board</primary>
</indexterm><indexterm><primary>widget</primary><secondary>bulletin board</secondary></indexterm> bulletin board widget and set some of its resources.
</para>
<programlisting>XtCreateManagedWidget BBOARD bboard XmBbulletinBoard $TOPLEVEL \
resizePolicy:RESIZE_NONE \
background:SkyBlue\
height:150 width:250</programlisting>
<para>The bulletin board widget's ID is saved in the environment variable <filename>$BBOARD</filename>. The widget's name is <command>bboard</command>. This
name is used by the Xt Intrinsics to set the values of resources that might
be named in an external resource file. The widget class is <command>XmBulletinBoard</command>. The bulletin board's parent widget is the widget ID contained
in the environment variable <filename>$TOPLEVEL</filename>. This is the topl-
evel widget created by the initializion command in the first line. The \
(backslash) at the end of the line tells <command>dtksh</command> that this
command continues on the next line.</para>
<para>The next six lines create a<indexterm><primary>pushbutton</primary>
</indexterm><indexterm><primary>widget</primary><secondary>pushbutton</secondary>
</indexterm> push button widget as a child of the bulletin board, and set
some of the push button's resources.</para>
<programlisting>XtCreateManagedWidget BUTTON pushbutton XmPushButton $BBOARD \
background:goldenrod \
foreground:MidnightBlue \
labelString:&rdquo;Push Here&rdquo;\
height:30 width:100 x:75 y:60\
shadowThickness:3</programlisting>
<para>This is basically the same procedure used to create the bulletin board,
except that the variable, name, class, and parent are different.</para>
<para>The next line causes the toplevel widget and all its children to be
realized.</para>
<programlisting>XtRealizeWidget $TOPLEVEL<indexterm><primary>XtrealizeWidget</primary></indexterm></programlisting>
<para>Finally, the<indexterm><primary>XtMainLoop</primary></indexterm> <command>XtMainLoop</command> command initiates a loop processing of events for the
widgets.</para>
<programlisting>XtMainLoop</programlisting>
<para>In this script, all that happens is the window appears on the display.
It stays there until you terminate the script, either by choosing <command>Close</command> on the Window Manager menu or by pressing CTRL C in the terminal
window from which you executed the script.</para>
</sect1>
<sect1 id="DKSUG.scr1.div.3">
<title>Adding a Callback<indexterm><primary>callback</primary></indexterm></title>
<para>To provide a function for the push button so that when it is pressed
a message appears in the terminal window and the script terminates, you have
to add a callback. Also, you must tell the push button about the existence
of this callback. The following is the script with the new code added:</para>
<programlisting>#!/usr/dt/bin/dtksh
activateCB() {
echo &ldquo;Pushbutton activated; normal termination.&rdquo;
exit 0
}
XtInitialize TOPLEVEL dttest2 Dtksh $0
XtSetValues $TOPLEVEL title:&rdquo;dttest2&rdquo;
XtCreateManagedWidget BBOARD bboard XmBulletinBoard $TOPLEVEL \
resizePolicy:RESIZE_NONE \
background:SkyBlue \
height:150 width:250
XtCreateManagedWidget BUTTON pushbutton XmPushButton $BBOARD \
background:goldenrod \
foreground:MidnightBlue \
labelString:&rdquo;Push Here&rdquo;\
height:30 width:100 x:75 y:60 shadowThickness:3
XtAddCallback $BUTTON activateCallback activateCB
XtRealizeWidget $TOPLEVEL
XtMainLoop</programlisting>
<para>The callback is the function <filename>activateCB()</filename>. You
typically add the callback to the push button after it (the push button)
has been created:</para>
<programlisting>XtAddCallback $BUTTON activateCallback activateCB</programlisting>
<para>Now the pushbutton knows about the callback. When you click the push
button, the function <filename>activateCB()</filename> is executed, and the
message &ldquo;<command>Pushbutton activated; normal termination.</command>&rdquo;
appears in the terminal window from which you executed the script. The script
is terminated by the call to the function <command>exit 0</command>.</para>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub Caret>
<?Pub *0000009074>

516
cde/doc/C/guides/dtkshGuide/ch03.sgm Normal file
View File

@@ -0,0 +1,516 @@
<!-- $XConsortium: ch03.sgm /main/8 1996/09/08 19:46:03 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="DKSUG.adv.div.1">
<title id="DKSUG.adv.mkr.1">Advanced Topics</title>
<para>Now that you have the basic information about <command>dtksh</command>,
this chapter introduces you to more advanced topics.</para>
<sect1 id="DKSUG.adv.div.2">
<title>Using Context Variables</title>
<para><command>dtksh</command> has a number of variables that provide context
to certain aspects of an application.</para>
<sect2 id="DKSUG.adv.div.3">
<title>Event Handler Context Variables<indexterm><primary>context variable</primary><secondary>event handler</secondary></indexterm><indexterm><primary>event handler</primary></indexterm></title>
<para>An application registers event handlers with a widget to specify an
action to occur when one of the specified events occurs. The action can
be any arbitrary <command>dtksh</command> command line. For example:</para>
<programlisting>XtAddEventHandler $W &ldquo;Button2MotionMask&ldquo; false &ldquo;ActivateProc&ldquo;
XtAddEventHandler $W &ldquo;ButtonPressMask|ButtonReleaseMask&ldquo; \
false &ldquo;echo action&ldquo;</programlisting>
<para>Two environment variables are defined to provide context to the event
handler:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="5.64in">
<colspec align="left" colwidth="100*">
<colspec align="left" colwidth="365*">
<tbody>
<row>
<entry align="left" valign="top"><para>EH_WIDGET</para></entry>
<entry align="left" valign="top"><para>Set to the ID of the widget for which
the event handler is registered.</para></entry></row>
<row>
<entry align="left" valign="top"><para>EH_EVENT</para></entry>
<entry align="left" valign="top"><para>Set to the address of the <command>XEvent</command> which triggered the event handler.</para></entry></row>
</tbody></tgroup></informaltable>
<para>Access to the fields within the <command>XEvent</command> structure
is shown in the following example:</para>
<programlisting>if [ ${EH_EVENT.TYPE} = &ldquo;ButtonPress&ldquo; ]; then
echo &ldquo;X = &ldquo;${EH_EVENT.XBUTTON.X}
echo &ldquo;Y = &ldquo;${EH_EVENT.XBUTTON.Y}
elif [ ${EH_EVENT.TYPE} = &ldquo;KeyPress&ldquo; ]; then
echo &ldquo;X = &ldquo;${EH_EVENT.XKEY.X}
echo &ldquo;Y = &ldquo;${EH_EVENT.XKEY.Y}
fi</programlisting>
</sect2>
<sect2 id="dksug.adv.div.4">
<title>Translation Context Variables<indexterm><primary>context variable</primary>
<secondary>translation</secondary></indexterm><indexterm><primary>translation</primary></indexterm></title>
<para>The Xt Intrinsics provides for event translations to be registered for
a widget. Context for event translation is provided in the same way it is
provided for event handlers. The two variables defined for translation commands
are:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.04in">
<colspec align="left" colwidth="196*">
<colspec align="left" colwidth="302*">
<tbody>
<row>
<entry align="left" valign="top"><para>TRANSLATION_WIDGET</para></entry>
<entry align="left" valign="top"><para>Set to the widget handle for the widget
for which the translation is registered.</para></entry></row>
<row>
<entry align="left" valign="top"><para>TRANSLATION_EVENT</para></entry>
<entry align="left" valign="top"><para>Set to the address of the <command>XEvent</command> that triggered the translation.</para></entry></row></tbody>
</tgroup></informaltable>
<para>Dot-notation provides access to the fields of the event:</para>
<programlisting>echo &ldquo;Event type = &ldquo;${TRANSLATION_EVENT.TYPE}
echo &ldquo;Display = &ldquo;${TRANSLATION_EVENT.XANY.DISPLAY}</programlisting>
</sect2>
<sect2 id="DKSUG.adv.div.5">
<title>Workspace Callback Context Variables<indexterm><primary>context variable</primary><secondary>workspace callback</secondary></indexterm><indexterm>
<primary>workspace callback</primary></indexterm><indexterm><primary>callback</primary><secondary>workspace</secondary></indexterm></title>
<para>An application has the ability to register a callback function that
is invoked whenever the user changes to a new workspace. When the callback
is invoked, two special environment variables are set, and can be accessed
by the shell callback code:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.00in">
<colspec align="left" colwidth="144*">
<colspec align="left" colwidth="351*">
<tbody>
<row>
<entry align="left" valign="top"><para>CB_WIDGET</para></entry>
<entry align="left" valign="top"><para>Set to the ID for the widget that is
invoking the callback.</para></entry></row>
<row>
<entry align="left" valign="top"><para>CB_CALL_DATA</para></entry>
<entry align="left" valign="top"><para>Set to the X atom that uniquely identifies
the new workspace. This can be converted to its string representation,
using the <command>XmGetAtomName</command> command.</para></entry></row></tbody>
</tgroup></informaltable>
</sect2>
<sect2 id="DKSUG.adv.div.6">
<title>Input Context Variables<indexterm><primary>context variable</primary>
<secondary>input</secondary></indexterm><indexterm><primary>input context
variable</primary></indexterm></title>
<para>The Xt Intrinsics provides the <command><indexterm><primary>XtAddInput</primary></indexterm>XtAddInput</command> facility, which allows an application
to register interest in any data available from a particular file descriptor.
When programming in C, the application provides a handler function, which
is invoked when input is available. It is up to the handler to read the
data from the input source and to handle character escaping and line continuations.
</para>
<para><command>dtksh</command> also supports the <command><indexterm><primary>XtAddInput</primary></indexterm>XtAddInput</command> facility, but takes it
a step further and makes it easier for shell programmers to use. By default,
when a shell script registers interest in a file descriptor, <command>dtksh</command> invokes the shell script's input handler only when a complete
line of text has been received. A complete line of text is defined as a
line terminated either by an unescaped newline character or by the end of
the file. The input handler is also called if no data is available and the
end of the file has been reached. The handler can then use <command><indexterm>
<primary>XtRemoveInput</primary></indexterm>XtRemoveInput</command> to remove
the input source and to close the file descriptor. The advantage of this
default behavior is that input handlers need not be concerned with escape
processing or with handling line continuations. The disadvantage is that
it assumes that all of the input is line-oriented and contains no binary
information.</para>
<para><command>dtksh</command> also supports a &ldquo;raw&rdquo;<indexterm>
<primary>input mode</primary></indexterm> input mode if the input source contains
binary information or if the input handler wants to read the data from the
input source directly. In raw mode, <command>dtksh</command> does not read
any of the data from the input source. Whenever <command>dtksh</command>
is notified that input is available on the input source, it invokes the shell
script's input handler. It is then the handler's responsibility to read
the incoming data, perform any required buffering and escape processing,
and detect when the end of the file has been reached (so that the input source
can be removed and the file descriptor closed). This mode seldom needs to
be used by a <command>dtksh</command> script.</para>
<para>Whether the input handler has been configured to operate in the default
mode or in raw mode, <command>dtksh</command> sets up several environment
variables before calling the shell script's input handler. These environment
variables provide the input handler with everything needed to handle the
incoming data. The environment variables are:</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.09in">
<colspec align="left" colwidth="140*">
<colspec align="left" colwidth="362*">
<tbody>
<row>
<entry align="left" valign="top"><para><filename>INPUT_LINE</filename></para></entry>
<entry align="left" valign="top"><para>If operating in the default mode, this
variable contains the next complete line of input available from the input
source. If <filename>INPUT_EOF</filename> is true, then there is no data
in this buffer. If operating in raw mode, then this variable always contains
an empty string.</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>INPUT_EOF</filename></para></entry>
<entry align="left" valign="top"><para>If operating in the default mode, this
variable is set to false anytime <filename>INPUT_LINE</filename> contains
data, and it is set to true when the end of file is reached. When the end
of file is reached, the shell script's input handler should unregister the
input source and close the file descriptor. If operating in raw mode, this
variable is always set to false.</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>INPUT_SOURCE</filename></para></entry>
<entry align="left" valign="top"><para>This indicates the file descriptor
for which input is available. If operating in raw mode, this file descriptor
is used to obtain the pending input. The file descriptor is also used to
close the input source, when no longer needed.</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>INPUT_ID</filename></para></entry>
<entry align="left" valign="top"><para>This indicates the ID returned by <command>XtAddInput</command>, when the input source was originally registered. This
information is needed to remove the input source with <command>XtRemoveInput</command>.</para></entry></row></tbody></tgroup></informaltable>
</sect2>
</sect1>
<sect1 id="DKSUG.adv.div.7">
<title>Accessing Event Subfields<indexterm><primary>event subfield</primary>
</indexterm></title>
<para>The <command>XEvent</command> structure has many different configurations,
based on the event's type. <command>dtksh</command> provides access only
to the most frequently used <command>XEvents</command>. Any of the other
standard <command>XEvents</command> can be accessed using the event type <command>XANY</command>, followed by any of the subfields defined by the <command>XANY</command> event structure, which includes the following subfields:</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>${TRANSLATION_EVENT.XANY.TYPE}</filename></para>
</listitem><listitem><para><filename>${TRANSLATION_EVENT.XANY.SERIAL}</filename></para>
</listitem><listitem><para><filename>${TRANSLATION_EVENT.XANY.SEND_EVENT}</filename></para>
</listitem><listitem><para><command>${TRANSLATION_EVENT.XANY.DISPLAY}</command></para>
</listitem><listitem><para><filename>${TRANSLATION_EVENT.XANY.WINDOW}</filename></para>
</listitem></itemizedlist>
<para><command>dtksh</command> supports full access to all of the event fields
for the following event types:</para>
<itemizedlist remap="Bullet1"><listitem><para><command>XANY</command></para>
</listitem><listitem><para><command>XBUTTON</command></para>
</listitem><listitem><para><command>XEXPOSE</command></para>
</listitem><listitem><para><command>XNOEXPOSE</command></para>
</listitem><listitem><para><command>XGRAPHICSEXPOSE</command></para>
</listitem><listitem><para><command>XKEY</command></para>
</listitem><listitem><para><command>XMOTION</command></para>
</listitem></itemizedlist>
<para>The following examples show how the subfields for the preceding event
types can be accessed:</para>
<programlisting>${TRANSLATION_EVENT.XBUTTON.X}
$(CB_CALL_DATA.EVENT.XKEY.STATE}
${EH_EVENT.XGRAPHICSEXPOSE.WIDTH}</programlisting>
</sect1>
<sect1 id="DKSUG.adv.div.8">
<title>Responding to a Window Manager Close Notice</title>
<para>When the user selects<indexterm><primary>window manager close notice</primary></indexterm> Close from the Window Manager menu for an application,
the application is terminated unless it has arranged to &ldquo;catch&rdquo;
the Close notification. If the application does not catch the notification,
then multiple windows managed by the application all disappear and application
data may be left in an undesirable state. To avoid this, <command>dtksh</command> provides for catching and handling the Close notification. The
application must:</para>
<itemizedlist remap="Bullet1"><listitem><para>Define a procedure to handle
the Close notification</para>
</listitem><listitem><para>Request notification when Close is selected</para>
</listitem><listitem><para>Override the response, so the application is not
shut down</para>
</listitem></itemizedlist>
<para>The following code illustrates this processing.</para>
<programlisting># This is the `callback' invoked when the user selects
# the `Close' menu item
WMCallback()
{
echo &ldquo;User has selected the Close menu item&ldquo;
}
# Create the toplevel application shell
XtInitialize TOPLEVEL test Dtksh $0 &ldquo;$@&ldquo;
XtDisplay DISPLAY $TOPLEVEL
# Request notification when the user selects the `Close'
# menu item
XmInternAtom DELETE_ATOM $DISPLAY &ldquo;WM_DELETE_WINDOW&ldquo; false
XmAddWMProtocolCallback $TOPLEVEL $DELETE_ATOM &ldquo;WMCallback&ldquo;
# Ask Motif to not automatically close down your
# application window
XtSetValues $TOPLEVEL deleteResponse:DO_NOTHING</programlisting>
</sect1>
<sect1 id="DKSUG.adv.div.9">
<title>Responding to a Session Manager Save State Notice<indexterm><primary>session manager save state notice</primary></indexterm></title>
<para>Session Manager allows applications to save their current state when
the user terminates the current session, so that when the user later restarts
the session, an application can return to the state it was in. In <command>dtksh</command>, this is accomplished by setting up a handler in a similar
way of handling a Close notification. If a handler is not set up, the application
has to be restarted manually in the new session, and the application does
not retain any state.</para>
<para>To set up a handler to save the current state, the application must:
</para>
<itemizedlist remap="Bullet1"><listitem><para>Define functions to save the
state at the end of the session and to restore it on startup</para>
</listitem><listitem><para>Register interest in the Session Manager notification
</para>
</listitem><listitem><para>Register the function to save the state</para>
</listitem><listitem><para>At startup, determine whether the saved state should
be restored</para>
</listitem></itemizedlist>
<para>The following code illustrates this process.</para>
<programlisting>#! /usr/dt/bin/dtksh
# Function invoked when the session is being ended by the user
SessionCallback()
{
# Get the name of the file into which we should save our
# session information
if DtSessionSavePath $TOPLEVEL PATH SAVEFILE; then
exec 9>$PATH
# Save off whether we are currently in an iconified state
if DtShellIsIconified $TOPLEVEL; then
print -u9 `Iconified'
else
print -u9 `Deiconified'
fi
# Save off the list of workspaces we currently reside in
if DtWsmGetWorkspacesOccupied $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) \
$(XtWindow &ldquo;-&ldquo; $TOPLEVEL) \
CURRENT_WS_LIST;
then
# Map the comma-separated list of atoms into
# their string representation
oldIFS=$IFS
IFS=&ldquo;,&ldquo;
for item in $CURRENT_WS_LIST;
do
XmGetAtomName NAME $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) \
$item
print -u9 $NAME
done
IFS=$oldIFS
fi
exec 9&lt;&amp;-
# Let the session manager know how to invoke us when
# the session is restored
DtSetStartupCommand $TOPLEVEL \
&ldquo;/usr/dt/contrib/dtksh/SessionTest $SAVEFILE&ldquo;
else
echo &ldquo;DtSessionSavePath FAILED!!&ldquo;
exit -3
fi
}
# Function invoked during a restore session; restores the
# application to its previous state
RestoreSession()
{
# Retrieve the path where our session file resides
if DtSessionRestorePath $TOPLEVEL PATH $1; then
exec 9&lt;$PATH
read -u9 ICONIFY
# Extract and restore our iconified state
case $ICONIFY in
Iconified) DtSetIconifyHint $TOPLEVEL True;;
*) DtSetIconifyHint $TOPLEVEL False;
esac
# Extract the list of workspaces we belong in, convert
# them to atoms, and ask the Workspace Manager to relocate
# us to those workspaces
WS_LIST=&ldquo;&ldquo;
while read -u9 NAME
do
XmInternAtom ATOM $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) \
$NAME False
if [ ${#WS_LIST} -gt 0 ]; then
WS_LIST=$WS_LIST,$ATOM
else
WS_LIST=$ATOM
fi
done
DtWsmSetWorkspacesOccupied $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) \
$(XtWindow &ldquo;-&ldquo; $TOPLEVEL) $WS_LIST
exec 9&lt;&amp;-
else
echo &ldquo;DtSessionRestorePath FAILED!!&ldquo;
exit -3
fi
}
################## Create the Main UI #######################
XtInitialize TOPLEVEL wmProtTest Dtksh $0 &ldquo;$@&ldquo;
XtCreateManagedWidget DA da XmDrawingArea $TOPLEVEL \
height:200 width:200
XmInternAtom SAVE_SESSION_ATOM $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) \
&ldquo;WM_SAVE_YOURSELF&ldquo; False
# If a command-line argument was supplied, then treat it as the
# name of the session file
if (( $# > 0))
then
# Restore to the state specified in the passed-in session file
XtSetValues $TOPLEVEL mappedWhenManaged:False
XtRealizeWidget $TOPLEVEL
XSync $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) False
RestoreSession $1
XtSetValues $TOPLEVEL mappedWhenManaged:True
XtPopup $TOPLEVEL GrabNone
else
# This is not a session restore, so come up in the default state
XtRealizeWidget $TOPLEVEL
XSync $(XtDisplay &ldquo;-&ldquo; $TOPLEVEL) False
fi
# Register the fact that we are interested in participating in
# session management
XmAddWMProtocols $TOPLEVEL $SAVE_SESSION_ATOM
XmAddWMProtocolCallback $TOPLEVEL $SAVE_SESSION_ATOM \
SessionCallback
XtMainLoop</programlisting>
</sect1>
<sect1 id="DKSUG.adv.div.10">
<title>Cooperating with Workspace Manager<indexterm><primary>workspace management</primary></indexterm></title>
<para><command>dtksh</command> provides access to all of the major Workspace
Manager functions of the Dt libraries, including functions for querying and
setting the set of workspaces with which an application is associated; for
querying the list of all workspaces; for querying and setting the current
workspace; and for requesting that an application be notified any time the
user changes to a different workspace.</para>
<para>From a user's perspective, workspaces are identified by a set of names,
but from the Workspace Manager's standpoint, workspaces are identified by
X atoms. Whenever the shell script asks for a list of workspace identifiers,
a string of X atoms is returned. If more than one X atom is present, then
the list is comma-separated. The Workspace Manager expects that the shell
script uses the same format when passing workspace identifiers back to
it. During a given session, it is safe for the shell script to work with
the X atoms, since they remain constant over the lifetime of the session.
However, as was shown in the Session Manager shell script example in the
previous section, if the shell script is going to save and restore workspace
identifiers, the identifiers must be converted from their X atom representation
to a string before they are saved. Then, when the session is restored, the
shell script needs to remap the names into X atoms before passing the information
on to the Workspace Manager. Mapping between X atoms and strings, and between
strings and X atoms, is accomplished using the following two commands:</para>
<itemizedlist remap="Bullet1"><listitem><para><command>XmInternAtom ATOM $DISPLAY
$WORKSPACE_NAME false</command></para>
</listitem><listitem><para><command>XmGetAtomName NAME $DISPLAY $ATOM</command></para>
</listitem></itemizedlist>
<para>Specific <command>dtksh</command> commands for dealing with workspace
management are documented in &ldquo;Built-in libDt Session Management Commands&rdquo;
in Appendix A.</para>
</sect1>
<sect1 id="DKSUG.adv.div.11">
<title>Creating Localized Shell Scripts<indexterm><primary>localized script</primary></indexterm><indexterm><primary>script</primary><secondary>localized</secondary></indexterm></title>
<para><command>dtksh</command> scripts are internationalized and then localized
in a process similar to C applications. All strings that may be presented
to the user are identified in the script. A post-processor extracts the strings
from the script and, from them, builds a catalogue, which can then be translated
to any desired locale. When the script executes, the current locale determines
which message catalog is searched for strings to display. When a string is
to be presented, it is identified by a message-set ID (corresponding to the
catalog) and a message number within the set. These values determine what
text the user sees. The following code illustrates the process:</para>
<programlisting># Attempt to open our message catalog
catopen MSG_CAT_ID &ldquo;myCatalog.cat&ldquo;
# The localized button label is in set 1, and is message # 2
XtCreatePushButton OK $PARENT ok \
labelString:$(catgets $MSG_CAT_ID 1 2 &ldquo;OK&ldquo;)
# The localized button label is in set 1, and is message #3
XtCreatePushButton CANCEL $PARENT cancel \
labelString:$(catgets $MSG_CAT_ID 1 3 &ldquo;Cancel&ldquo;)
# Close the message catalog, when no longer needed
catclose $MSG_CAT_ID</programlisting>
<para>It is important to note that the file descriptor returned by <command>catopen</command> must be closed using <command>catclose</command> and not
by using the kshell <command>exec</command> command.</para>
</sect1>
<sect1 id="DKSUG.adv.div.12">
<title>Using dtksh to Access X Drawing Functions<indexterm><primary>drawing
functions</primary></indexterm></title>
<para><command>dtksh</command> commands include standard Xlib drawing functions
to draw lines, points, segments, rectangles, arcs, and polygons. In the standard
C programming environment, these functions take a graphics context (GC) as
an argument, in addition to the drawing data. In <command>dtksh</command>
drawing functions, a collection of GC options are specified in the parameter
list to the command.</para>
<para>By default, the drawing commands create a GC that is used for that specific
command and then discarded. If the script specifies the <filename>-gc</filename>
option, the name of a graphics context object can be passed to the command.
This GC is used in interpreting the command, and the variable is updated
with any modifications to the GC performed by the command.</para>
<informaltable>
<tgroup cols="2" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.54in">
<colspec align="left" colwidth="201*">
<colspec align="left" colwidth="338*">
<tbody>
<row>
<entry align="left" valign="top"><para><filename>-gc</filename> &lt;<symbol role="Variable">GC</symbol>></para></entry>
<entry align="left" valign="top"><para><symbol role="Variable">&lt;GC></symbol>
is the name of an environment variable which has not yet been initialized
or which has been left holding a graphic context by a previous drawing
command. If this option is specified, then it must be the first GC option
specified.</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>-foreground</filename> &lt;<symbol role="Variable">color</symbol>></para></entry>
<entry align="left" valign="top"><para>The foreground color, which may be
either the name of a color or a pixel number.</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>-background</filename> &lt;<symbol role="Variable">color</symbol>></para></entry>
<entry align="left" valign="top"><para>The background color, which may be
either the name of a color or a pixel number.</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>-font</filename> &lt;<symbol role="Variable">font name</symbol>></para></entry>
<entry align="left" valign="top"><para>The name of the font to be used.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>-line_width</filename> &lt;<symbol role="Variable">number</symbol>></para></entry>
<entry align="left" valign="top"><para>The line width to be used during drawing.
</para></entry></row>
<row>
<entry align="left" valign="top"><para><filename>-function</filename> &lt;<symbol role="Variable">drawing function</symbol>></para></entry>
<entry align="left" valign="top"><para>The drawing function, which can be
<command>xor, or, clear, and, copy, noop, nor, nand, set, invert, equiv,
andReverse, orReverse,</command> or <command>copyInverted</command>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>-line_style</filename> &lt;<symbol role="Variable">style</symbol>></para></entry>
<entry align="left" valign="top"><para>The line style, which can be any of
the following: <command>LineSolid</command>, <command>LineDoubleDash</command>,
or <command>LineOnOffDash</command>.</para></entry></row></tbody></tgroup>
</informaltable>
</sect1>
<sect1 id="DKSUG.adv.div.13">
<title>Setting Widget Translations<indexterm><primary>translation</primary>
</indexterm><indexterm><primary>widget</primary><secondary>translations</secondary>
</indexterm></title>
<para><command>dtksh</command> provides mechanisms for augmenting, overriding,
and removing widget translations, much as in the C programming environment.
In C, an application installs a set of translation action procedures, which
can then be attached to specific sequences of events (translations are composed
of an event sequence and the associated action procedure). Translations within <command>dtksh</command> are handled in a similar fashion, except only a single action
procedure is available. This action procedure, named <filename>ksh_eval</filename>,
interprets any parameters passed to it as <command>dtksh</command> commands
and evaluates them when the translation is triggered. The following shell
script segment gives an example of how translations can be used:</para>
<programlisting>BtnDownProcedure()
{
echo &ldquo;Button Down event occurred in button &ldquo;$1
}
XtCreateManagedWidget BUTTON1 button1 XmPushButton $PARENT \
labelString:&ldquo;Button 1&ldquo; \
translations:'#augment
&lt;EnterNotify>:ksh_eval(&ldquo;echo Button1 entered&ldquo;)
&lt;Btn1Down>:ksh_eval(&ldquo;BtnDownProcedure 1&ldquo;)'
XtCreateManagedWidget BUTTON2 button2 XmPushButton $PARENT \
labelString:&ldquo;Button 2&ldquo;
XtOverrideTranslations $BUTTON2 \
'#override
&lt;Btn1Down>:ksh_eval(&ldquo;BtnDownProcedure 2&ldquo;)'</programlisting>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub Caret>
<?Pub *0000029103>

352
cde/doc/C/guides/dtkshGuide/ch04.sgm Normal file
View File

@@ -0,0 +1,352 @@
<!-- $XConsortium: ch04.sgm /main/7 1996/09/08 19:46:13 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="DKSUG.scr2.div.1">
<title>A Complex Script<indexterm><primary>script, complex</primary></indexterm></title>
<para>This chapter describes a much more complex script than that described
in Chapter 2. Because of its length, the entire script is listed in Appendix
C. Remember that this guide is not a tutorial on KornShell programming.
If you are not familiar with KornShell programming, you should obtain a
book on the subject and have it handy for reference.</para>
<sect1 id="DKSUG.scr2.div.2">
<title>Using script_find</title>
<para>The script,<indexterm><primary>script_find</primary></indexterm> <filename>script_find</filename>, demonstrates how you can use <command>dtksh</command>
to provide a graphical interface to the <command>find</command> command.
<filename>script_find</filename> produces a window within which you can
specify parameters for the <command>find</command> command. To fully understand
the script, you should be familiar with the <command>find</command> command
and you should have its man page available. A number of the toggle button
menu choices in the window produced by <filename>script_find</filename> require
some knowledge of the <command>find</command> command.</para>
<para>The script's window allows you to specify a search directory and a file
name. Other options allow you to place restrictions on the type of file
system to search and the file type on which to match. Figure 4-1 shows the
script's window.</para>
<figure>
<title>Window for script_find</title>
<graphic id="DKSUG.scr2.grph.1" entityref="DKSUG.scr2.fig.1"></graphic>
</figure>
<para>Enter the search directory and file name you're looking for in the text
fields at the top of the window. In addition, select any applicable choice
(or choices) from the five toggle buttons. You can further restrict the
search with the option menus. When you have made all the necessary selections,
click OK. If all is well, a window appears shortly thereafter and displays
the results of the <command>find</command> operation. An error dialog appears
if you don't specify a search directory or file name, or if the specified
search directory is invalid. For example, suppose you want to find a file
called <filename>two_letter_calls</filename>, and you think it resides somewhere
in the directory <filename>/users/dlm</filename>. When you enter the directory
in the Search Directory text field, you inadvertently type
<filename>/users/dln</filename> instead of /<filename>users/dlm</filename>. When you click OK
or Apply, <filename>script_find</filename> can't find the directory <filename>/users/dln</filename>, so it creates the error dialog to notify you of this.
</para>
<figure>
<title>script_find error dialog</title>
<graphic id="DKSUG.scr2.grph.2" entityref="DKSUG.scr2.fig.2"></graphic>
</figure>
<para>When you correct the mistake, <filename>script_find</filename> then
executes properly and creates a <command>dtterm</command> window within which
it displays the complete path of the file you requested, providing that the
file is found.</para>
<figure>
<title>Window showing complete path</title>
<graphic id="DKSUG.scr2.grph.3" entityref="DKSUG.scr2.fig.3"></graphic>
</figure>
<para>If <filename>script_find</filename> cannot find the file in the specified
directory, nothing appears in the <command>dtterm</command> window.</para>
</sect1>
<sect1 id="DKSUG.scr2.div.3">
<title>Analyzing script_find</title>
<para>The structure of <filename>script_find</filename> is similar to a C
program: some functions and callbacks appear first, followed by the main
script.</para>
<para>The first two lines of the script are important, and should be included
in every <command>dtksh</command> script you write:</para>
<programlisting>#! /usr/dt/bin/dtksh
. /usr/dt/lib/dtksh/DtFunc.dtsh</programlisting>
<para>The first line executes the <command>dtksh</command> system and the
second loads the <command>dtksh</command> convenience functions. The second
line wasn't used in the scripts described in Chapter 2 because those scripts
did not use any <command>dtksh</command> convenience functions.</para>
<sect2 id="DKSUG.scr2.div.4">
<title>Functions and Callbacks<indexterm><primary>callback</primary><secondary>script_find</secondary></indexterm></title>
<para><filename>script_find</filename> has the following functions and callbacks:
</para>
<itemizedlist remap="Bullet1"><listitem><para><filename>PostErrorDialog()</filename></para>
</listitem><listitem><para><filename>OkCallback()</filename></para>
</listitem><listitem><para>LoadStickyValues()</para>
</listitem><listitem><para><filename>EvalCmd()</filename></para>
</listitem><listitem><para><filename>RetrieveAndSaveCurrentValues()</filename></para>
</listitem></itemizedlist>
<sect3 id="DKSUG.scr2.div.5">
<title>PostErrorDialog()</title>
<para>This function is called when an error is detected, such as when the
user enters an invalid directory. The function calls the convenience function
<filename><indexterm><primary>DtkshDisplayErrorDialog</primary></indexterm>DtkshDisplayErrorDialog()</filename> which displays a dialog box whose title is Find Error and whose
message is contained in the variable $1, which is passed from the calling
location.</para>
<programlisting>dialogPostErrorDialog()
{
DtDisplayErrorDialog &ldquo;Find Error&rdquo; &ldquo;$1&rdquo; \
DIALOG_PRIMARY_APPLICATION_MODAL
}</programlisting>
<para>The last parameter, <computeroutput>DIALOG_PRIMARY_APPLICATION_MODAL</computeroutput>, tells <command>dtksh</command> to create a dialog that
must be responded to before any other interaction can occur.</para>
</sect3>
<sect3 id="DKSUG.scr2.div.6">
<title>OkCallback()</title>
<para><filename>OkCallback()</filename> is called when either the OK or Apply
button on the main <filename>script_find</filename> window is pressed. If
the OK button is pressed, the script_find window is unmanaged. For either
Apply or OK, the input search directory is validated; if it is invalid, then <filename>OkCallback()</filename> calls <filename>PostErrorDialog()</filename>. If
it is valid, checks are made on the status of the toggle buttons on the <filename>script_find</filename> window and corresponding adjustments are made to the
variable <filename>$CMD</filename>. This variable contains the entire command
that is ultimately executed.</para>
</sect3>
<sect3 id="DKSUG.scr2.div.7">
<title>LoadStickyValues()</title>
<para>This function is called from the main program after the window has been
created and managed. It loads all the values from the most recent execution
of the script. These values are saved in a file called
<filename>Find.sticky</filename> by the function <filename>RetrieveandSaveCurrentValues()</filename>.
</para>
</sect3>
<sect3 id="DKSUG.scr2.div.8">
<title>EvalCmd()</title>
<para><filename>EvalCmd()</filename> is used by <filename>LoadStickyValues()</filename>
to evaluate each line in <filename>Find.sticky</filename> as
a <command>dtksh</command> command. The following is a list of a <filename>Find.sticky</filename> file:</para>
<programlisting>XmTextSetString $SD &ldquo;/users/dlm&rdquo;<indexterm>
<primary>XmTextSetString</primary></indexterm>
XmTextFieldSetInsertionPosition $SD 10<indexterm><primary>XmTextFieldSetInsertionPosition</primary></indexterm>
XmTextSetString $FNP &ldquo;two_letter_calls&rdquo;<indexterm><primary>XmTextSetString</primary></indexterm>
XmTextFieldSetInsertionPosition $FNP 16<indexterm><primary>XmTextFieldSetInsertionPosition</primary></indexterm>
XtSetValues $FSTYPE menuHistory:$NODIR<indexterm><primary>XtSetValues</primary>
</indexterm>
XtSetValues $FILETYPE menuHistory:$NOTYPE<indexterm><primary>XtSetValues</primary>
</indexterm>
XmToggleButtonSetState $T2 true false<indexterm><primary>XmToggleButtonSetState</primary></indexterm>
XmToggleButtonSetState $T4 true false<indexterm><primary>XmToggleButtonSetState</primary></indexterm></programlisting>
</sect3>
<sect3 id="DKSUG.scr2.div.9">
<title>RetrievAndSaveCurrentValues()</title>
<para><filename>RetrieveAndSaveCurrentValues()</filename> retrieves the current
settings and values of the widgets in the <filename>script_find</filename>
window and saves them in the file <filename>Find.sticky</filename>. <filename>Find.sticky</filename> is then used by <filename>LoadStickyValues()</filename>
the next time the script is executed.</para>
</sect3>
</sect2>
<sect2 id="DKSUG.scr2.div.10">
<title>Main Script</title>
<para>The remainder of the script is the equivalent of <filename>Main()</filename>
in a C program. It initializes the Xt Intrinsics and creates all the widgets
used in the <filename>script_find</filename> window. The <command>set -f</command> in the first line tells <command>dtksh</command> to suppress expansion
of wildcard characters in path names. This is necessary so that the <command>find</command> command can perform this expansion.</para>
<para>The <filename>script_find</filename> window (see Figure 4-4) consists
of a Form widget with four areas. The areas are marked by Separator widgets,
and each area has several widgets, all of which are children of the Form.
</para>
<figure>
<title>Widgets in script_find window</title>
<graphic id="DKSUG.scr2.grph.4" entityref="DKSUG.scr2.fig.4"></graphic>
</figure>
<para>The widgets are created in sequence by area, from top to bottom.</para>
<sect3 id="DKSUG.scr2.div.11">
<title>Initialize</title>
<para>Initialize is accomplished by the Xt Intrinsics function <command>XtInitialize</command>:</para>
<programlisting>XtInitialize TOPLEVEL find Dtksh $0 &ldquo;${@:-}&rdquo;<indexterm>
<primary>XtInitialize</primary></indexterm></programlisting>
<para>This creates a top-level shell that serves as the parent of a Form widget,
which is created next.</para>
</sect3>
<sect3 id="DKSUG.scr2.div.12">
<title>Create a Form Widget<indexterm><primary>widget</primary><secondary>form</secondary></indexterm><indexterm><primary>create form widget</primary>
</indexterm></title>
<para>A Form widget is used as the main parent widget. Form is a Manager
widget that allows you to place constraints on its children. Most of the
widgets in the main <filename>script_find</filename> window are children
of the Form. The description of the creation of the rest of the widgets
is separated into the four areas of the window (see Figure 4-4).</para>
</sect3>
<sect3 id="DKSUG.scr2.div.13">
<title>First Area</title>
<para>The first area consists of two Label widgets, two TextField widgets,
and a Separator widget that separates the first and second areas.</para>
<figure>
<title>First area of <filename>script_find</filename> Window</title>
<graphic id="DKSUG.scr2.grph.5" entityref="DKSUG.scr2.fig.5"></graphic>
</figure>
<para>The following code segment creates and positions the first Label widget
and positions it within the Form using the <command>DtkshAnchorTop</command>
and <command>DtkshAnchorLeft</command> convenience functions:</para>
<programlisting>XtCreateManagedWidget SDLABEL sdlabel XmLabel $FORM \<indexterm>
<primary>XtCreateManagedWidget</primary></indexterm>
labelString:&rdquo;Search Directory:&rdquo; \
$(DtkshAnchorTop 12) \
$(DtkshAnchorLeft 10)</programlisting>
<para>The following code segment creates and positions the first TextField
widget. Note that it is positioned in relation to both the Form and the
Label widget.</para>
<programlisting>XtCreateManagedWidget SD sd XmText $FORM \<indexterm><primary>XtCreateManagedWidget</primary></indexterm>
columns:30 \
value:&rdquo;.&rdquo; \
$(DtkshAnchorTop 6) \
$(DtkshRightOf $SDLABEL 10) \
$(DtkshAnchorRight 10) \
navigationType:EXCLUSIVE_TAB_GROUP
XmTextFieldSetInsertionPosition $SD 1<indexterm><primary>XmTextFieldSetInsertionPosition</primary></indexterm></programlisting>
<para>The remaining Label widget and TextField widget are created in the same
manner.</para>
<para>The Separator widget is created as a child of the Form widget and positioned
under the second TextField widget.<indexterm><primary>widget</primary><secondary>separator</secondary></indexterm><indexterm><primary>create separator widget</primary></indexterm></para>
<programlisting>XtCreateManagedWidget SEP sep XmSeparator $FORM \<indexterm>
<primary>XtCreateManagedWidget</primary></indexterm>
separatorType:SINGLE_DASHED_LINE \
$(DtkshUnder $FNP 10) \
$(DtkshSpanWidth)</programlisting>
</sect3>
<sect3 id="DKSUG.scr2.div.14">
<title>Second Area</title>
<para>The second area consists of a RowColumn widget, five ToggleButton gadgets,
and another Separator widget.</para>
<figure>
<title>Second Area of <filename>script_find</filename> Window</title>
<graphic id="DKSUG.scr2.grph.6" entityref="DKSUG.scr2.fig.6"></graphic>
</figure>
<para>A gadget is a widget that relies on its parent for many of its attributes,
thus saving memory resources.</para>
<para>The RowColumn widget is created as a child of the Form widget, and
positioned directly under the Separator widget created in the first area.
</para>
<programlisting>XtCreateManagedWidget RC rc XmRowColumn $FORM \<indexterm>
<primary>XtCreateManagedWidget</primary></indexterm>
orientation:HORIZONTAL \
numColumns:3 \
packing:PACK_COLUMN \
$(DtkshUnder $SEP 10) \
$(DtkshSpanWidth 10 10) \
navigationType:EXCLUSIVE_TAB_GROUP</programlisting>
<para>The five ToggleButton gadgets are created as children of the RowColumn
using the convenience function <command>DtkshAddButtons</command>:</para>
<programlisting>DtkshAddButtons -w $RC XmToggleButtonGadget \<indexterm><primary>DtkshAddButtons</primary></indexterm>
T1 &ldquo;Cross Mount Points&rdquo; &ldquo;&ldquo;\
T2 &ldquo;Print Matching Filenames&rdquo; &ldquo;&ldquo;\
T3 &ldquo;Search Hidden Subdirectories&rdquo; &ldquo;&ldquo;\
T4 &ldquo;Follow Symbolic Links&rdquo; &ldquo;&ldquo;\
T5 &ldquo;Descend Subdirectories First&rdquo; &ldquo;&ldquo;</programlisting>
<para>Another Separator is then created to separate the second and third areas.
Note that this Separator widget ID is called <filename>SEP2</filename>.
</para>
<programlisting>XtCreateManagedWidget SEP2 sep XmSeparator $FORM \<indexterm>
<primary>XtCreateManagedWidget</primary></indexterm>
separatorType:SINGLE_DASHED_LINE \
$(DtkshUnder $RC 10) \
$(DtkshSpanWidth)</programlisting>
</sect3>
<sect3 id="DKSUG.scr2.div.15">
<title>Third Area</title>
<para>The third area consists of two option menus and another Separator widget.
</para>
<figure>
<title>Third area of <filename>script_find</filename> Window</title>
<graphic id="DKSUG.scr2.grph.7" entityref="DKSUG.scr2.fig.7"></graphic>
</figure>
<para>The Option Menus are pull-down menus. When the user clicks the option
menu button, a menu pane with a number of choices appears. The user drags
the pointer to the appropriate choice and releases the mouse button. The
menu pane disappears and the option menu button label displays the new choice.<indexterm>
<primary>menu, create</primary></indexterm><indexterm><primary>create menu</primary></indexterm></para>
<para>The first option menu menu pane consists of a number of push button
gadgets, representing various restrictions that can be imposed upon the <command>find</command> command:</para>
<programlisting>XmCreatePulldownMenu PANE $FORM pane <indexterm><primary>XmCreatePulldownMenu</primary></indexterm>
DtkshAddButtons -w $PANE XmPushButtonGadget \<indexterm><primary>DtkshAddButtons</primary></indexterm>
NODIR &ldquo;no restrictions&rdquo; &ldquo;&ldquo;\
NFS &ldquo;nfs&rdquo; &ldquo;&ldquo;\
CDFS &ldquo;cdfs&rdquo; &ldquo;&ldquo;\
HFS &ldquo;hfs&rdquo; &ldquo;&ldquo;
Next, the Option Menu button itself is created and managed, with the
menu pane just created (<filename>$PANE</filename>) identified as a <command>subMenuId</command>:
XmCreateOptionMenu FSTYPE $FORM fstype \<indexterm><primary>XmCreateOptionMenu</primary></indexterm>
labelString:&rdquo;Restrict Search To File System Type:&rdquo; \
menuHistory:$NODIR \
subMenuId:$PANE \
$(DtkshUnder $SEP2 20) \
$(DtkshSpanWidth 10 10) \
navigationType:EXCLUSIVE_TAB_GROUP
XtManageChild $FSTYPE<indexterm><primary>XtManageChild</primary></indexterm></programlisting>
<para>The second option menu button is created in the same manner. It provides
further restrictions on the <command>find</command> command.</para>
<para>The third separator is created in the same manner as the other separators.
</para>
</sect3>
<sect3 id="DKSUG.scr2.div.16">
<title>Fourth Area</title>
<para>The fourth area consists of four push button widgets, all children of
the Form widget.</para>
<graphic id="DKSUG.scr2.igrph.1" entityref="DKSUG.scr2.fig.8"></graphic>
<para>The four push buttons are used as follows:</para>
<itemizedlist remap="Bullet1"><listitem><para>OK executes the <command>find</command> command with the parameters input in the <filename>script_find</filename>
window and removes the <filename>script_find</filename> window.
</para>
</listitem><listitem><para>Apply executes the <command>find</command> command
with the parameters input in the <filename>script_find</filename> window
but does not remove the <filename>script_find</filename> window.</para>
</listitem><listitem><para>Close terminates <filename>script_find</filename>
without executing the <command>find</command> command.</para>
</listitem><listitem><para><command>Help</command> creates a dialog box with
information on the use of <filename>script_find</filename>.</para>
</listitem></itemizedlist>
<para>The push buttons are created and positioned in much the same manner
as any of the other widgets, although they are each labeled differently.
The following code segment shows how the OK push button is created:</para>
<programlisting>XtCreateManagedWidget OK ok XmPushButton $FORM \<indexterm>
<primary>XtCreateManagedWidget</primary></indexterm>
labelString:&rdquo;Ok&rdquo; \
$(DtkshUnder $SEP3 10) \
$(DtkshFloatLeft 4) \
$(DtkshFloatRight 24) \
$(DtkshAnchorBottom 10)
XtAddCallback $OK activateCallback &ldquo;OkCallback&rdquo;<indexterm><primary>XtAddCallback</primary></indexterm></programlisting>
</sect3>
<sect3 id="DKSUG.scr2.div.17">
<title>Set Operating Parameters</title>
<para><command>XtSetValues</command> is used to set some initial operating
parameters:</para>
<programlisting>XtSetValues $FORM \<indexterm><primary>XtSetValues</primary>
</indexterm>
initialFocus:$SD \
defaultButton:$OK \
cancelButton:$CLOSE \
navigationType:EXCLUSIVE_TAB_GROUP</programlisting>
<itemizedlist remap="Bullet1"><listitem><para>Initial focus is set to the
first TextField widget in the first area.</para>
</listitem><listitem><para>Default button is set to the OK push button in
the fourth area.</para>
</listitem><listitem><para>Cancel button is set to the Close button in the
fourth area.</para>
</listitem><listitem><para>Navigation type is set to <computeroutput>EXCLUSIVE_TAB_GROUP.</computeroutput></para>
</listitem></itemizedlist>
<para>The following line configures the TextField widgets so that pressing
the return key does not activate the default button within the Form. See
the description of <computeroutput>EXCLUSIVE_TAB_GROUP</computeroutput> in
Appendix B for more information on its use.</para>
<programlisting>DtkshSetReturnKeyControls $SD $FNP $FORM $OK</programlisting>
</sect3>
<sect3 id="DKSUG.scr2.div.18">
<title>Realize and Loop</title>
<para>The last three lines of the script load the previous values of the <filename>script_find</filename> window, realize the top-level widget, and then enter
a loop waiting for user input.</para>
<programlisting>LoadStickyValues
XtRealizeWidget $TOPLEVEL<indexterm><primary>XtRealizeWidget</primary></indexterm>
XtMainLoop<indexterm><primary>XtMainLoop</primary></indexterm><?Pub Caret></programlisting>
</sect3>
</sect2>
</sect1>
</chapter>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub *0000021832>

BIN
cde/doc/C/guides/dtkshGuide/graphics/area1.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/area2.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/area3.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/area4.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/dttest1.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/finderr.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/findterm.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/findwin.tif Normal file
View File

Binary file not shown.

BIN
cde/doc/C/guides/dtkshGuide/graphics/labfindw.tif Normal file
View File

Binary file not shown.

182
cde/doc/C/guides/dtkshGuide/preface.sgm Normal file
View File

@@ -0,0 +1,182 @@
<!-- $XConsortium: preface.sgm /main/8 1996/08/25 15:09:35 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. -->
<preface id="DKSUG.Pref.div.1">
<title>Preface</title>
<para>The <emphasis>Desktop KornShell User's Guide</emphasis> provides the
information you need to create Motif applications with KornShell (kshell)
scripts. In addition to the basic information you'll need to get started,
several example scripts of increasing complexity are described. Throughout
this guide the term <command>dtksh</command> means the Desktop KornShell.
</para>
<sect1 id="DKSUG.Pref.div.2">
<title>Who Should Use This Guide</title>
<para>This guide is intended for programmers who want a quick and easy means
of creating Motif applications, but don't have the time, knowledge, or inclination
to use the C programming language. A good understanding of kshell programming,
Motif, the Xt Intrinsics, and, to a lesser extent, Xlib is needed. An understanding
of C would also be helpful.</para>
</sect1>
<sect1 id="DKSUG.Pref.div.3">
<title>How This Guide Is Organized</title>
<para><emphasis role="Lead-in">Chapter 1, &ldquo;Introduction to Desktop KornShell,&rdquo;</emphasis> describes the basic information you need to begin writing Motif
applications in <command>dtksh</command> scripts.</para>
<para><emphasis role="Lead-in">Chapter 2, &ldquo;A Sample Script,&rdquo;</emphasis> describes two simple <command>dtksh</command> scripts. The first
script creates a push button widget within a bulletin board widget. The
second script expands the first by adding a callback for the push button.
</para>
<para><emphasis role="Lead-in">Chapter 3, &ldquo;Advanced Topics,&rdquo;</emphasis> describes more advanced topics pertaining to <command>dtksh</command>
scripts.</para>
<para><emphasis role="Lead-in">Chapter 4, &ldquo;A Complex Script,&rdquo;</emphasis> describes a much more complex script than either of the ones
described in Chapter 2. This script creates a graphic interface to the <command>find</command> command.</para>
<para><emphasis role="Lead-in">Appendix A, &ldquo;dtksh Commands,&rdquo;</emphasis> lists all the <command>dtksh</command> commands.</para>
<para><emphasis role="Lead-in">Appendix B, &ldquo;dtksh Convenience Functions,&rdquo;</emphasis> contains man pages for commands or functions that are not documented
elsewhere.</para>
<para><emphasis role="Lead-in">Appendix C, &ldquo;Listing for script_find,&rdquo;</emphasis> contains the complete listing of the complex script described
in Chapter 4.</para>
</sect1>
<sect1 id="DKSUG.Pref.div.4">
<title>Related Books</title>
<para>The following books provide information on kshell programming, Motif,
the Xt Intrinsics, and Xlib:</para>
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Desktop KornShell
Graphical Programming For the Common Desktop Environment Version 1.0,</emphasis>
by J. Stephen Pendergrast, Jr., published by Addison-Wesley, Reading, MA
01867.</para>
</listitem><listitem><para><emphasis>The New KornShell Command and Programming
Language</emphasis>, by Morris I. Bolsky and David G. Korn, published by
Prentice-Hall, Englewood Cliffs, NJ 07632.</para>
</listitem><listitem><para><emphasis>KornShell Programming Tutorial</emphasis>,
by Barry Rosenberg, published by Addison-Wesley, Reading, MA 01867.</para>
</listitem><listitem><para><emphasis>Motif Programmer's Guide</emphasis>,
Open Software Foundation, 11 Cambridge Center, Cambridge, MA 02142, published
by Prentice-Hall, Englewood Cliffs, NJ 07632.</para>
</listitem><listitem><para><emphasis>Motif Programmer's Reference</emphasis>,
Open Software Foundation, 11 Cambridge Center, Cambridge, MA 02142, published
by Prentice-Hall, Englewood Cliffs, NJ 07632.</para>
</listitem><listitem><para><emphasis>Motif Reference Guide</emphasis>,
by Douglas A. Young, published by Prentice-Hall, Englewood Cliffs, NJ 07632.
</para>
</listitem><listitem><para><emphasis>Mastering Motif Widgets</emphasis> (Second
Edition), by Donald L. McMinds, published by Addison-Wesley, Reading, MA
01867</para>
</listitem><listitem><para><emphasis>The X Window System Programming and Applications
with Xt Motif Edition</emphasis>, by Douglas A. Young, published by Prentice-Hall,
Englewood Cliffs, NJ 07632.</para>
</listitem><listitem><para><emphasis>The Definitive Guides to the X Window
System, Volume 1: Xlib Programming Manual</emphasis>, by Adrian Nye, published
by O'Reilly and Associates, Sebastopol, CA 95472.</para>
</listitem><listitem><para><emphasis>The Definitive Guides to the X Window
System, Volume 2: Xlib Reference Manual</emphasis>, edited by Adrian Nye,
published by O'Reilly and Associates, Sebastopol, CA 95472.</para>
</listitem><listitem><para><emphasis>The Definitive Guides to the X Window
System, Volume 3: X Window System User's Guide</emphasis>, by Valerie Quercia
and Tim O'Reilly, published by O'Reilly and Associates, Sebastopol, CA 95472.
</para>
</listitem><listitem><para><emphasis>The Definitive Guides to the X Window
System, Volume 4: X Toolkit Intrinsics Programming Manual</emphasis>, by
Adrian Nye and Tim O'Reilly, published by O'Reilly and Associates, Sebastopol,
CA 95472.</para>
</listitem><listitem><para><emphasis>The Definitive Guides to the X Window
System, Volume 5: X Toolkit Intrinsics Reference Manual,</emphasis> edited
by Tim O'Reilly, published by O'Reilly and Associates, Sebastopol, CA 95472.
</para>
</listitem><listitem><para><emphasis>The Definitive Guides to the X Window
System, Volume 6: Motif Programming Manual</emphasis>, by Dan Heller, published
by O'Reilly and Associates, Sebastopol, CA 95472.</para>
</listitem></itemizedlist>
</sect1>
<sect1 id="DKSUG.Pref.div.4a">
<title>What DocBook SGML Markup Means</title>
<para>This book is written in the Structured Generalized Markup
Language (SGML) using the DocBook Document Type Definition (DTD).
The following table describes the DocBook markup used for
various semantic elements.
</para>
<table id="DKSUG.Pref.tbl.1" frame="Topbot">
<title>DocBook SGML Markup</title>
<tgroup cols="3" colsep="0" rowsep="0">
<colspec colwidth="1.65in">
<colspec colwidth="2.63in">
<colspec colwidth="2.92in">
<thead>
<row>
<entry align="left" valign="bottom"><para><literal>Markup Appearance</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Semantic Element(s)</literal></para></entry>
<entry align="left" valign="bottom"><para><literal>Example</literal></para></entry></row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><para><command>AaBbCc123</command></para></entry>
<entry align="left" valign="top"><para>The names of commands.</para></entry>
<entry align="left" valign="top"><para>Use the <command>ls</command> command to list files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><literal>AaBbCc123</literal></para></entry>
<entry align="left" valign="top"><para>The names of command options.</para></entry>
<entry align="left" valign="top"><para>Use <command>ls</command> <literal>&minus;a</literal>
to list all files.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><symbol role="Variable">AaBbCc123</symbol></para></entry>
<entry align="left" valign="top"><para>Command-line placeholder:
replace with a real name or value.</para></entry>
<entry align="left" valign="top"><para>To delete a file, type <command>rm</command> <symbol role="Variable">filename</symbol>.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>AaBbCc123</filename></para></entry>
<entry align="left" valign="top"><para>The names of files and
directories.</para></entry>
<entry align="left" valign="top"><para>Edit your <filename>.login</filename>
file.</para></entry>
</row>
<row>
<entry align="left" valign="top"><para><emphasis>AaBbCc123</emphasis></para></entry>
<entry align="left" valign="top"><para>Book titles, new words or terms, or
words to be emphasized.</para></entry>
<entry align="left" valign="top"><para>Read Chapter 6 in <emphasis>User's
Guide</emphasis>.
These are called <emphasis>class</emphasis> options.
You <emphasis>must</emphasis> be root to do this.</para></entry>
</row></tbody></tgroup></table>
</sect1>
<sect1 id="DKSUG.Pref.div.5">
<title>Shell Prompt Characters</title>
<para>The following table shows shell prompt characters
used in this book.</para>
<table id="DKSUG.Pref.tbl.2" frame="Topbot">
<title>Shell Prompt Characters</title>
<tgroup cols="3" colsep="0" rowsep="0">
<?PubTbl tgroup dispwid="6.33in">
<colspec colname="col1" colwidth="128*">
<colspec colname="col2" colwidth="201*">
<colspec colname="col3" colwidth="193*">
<spanspec nameend="col2" namest="col1" spanname="1to2">
<thead>
<row><entry align="left" valign="bottom"><para><literal>Character</literal></para></entry><entry align="left" valign="bottom"><para><literal>Meaning</literal></para></entry><entry align="left" valign="bottom"><para><literal>Example</literal></para></entry></row></thead>
<tbody>
<row>
<entry align="left" valign="top"><para><filename>%</filename></para></entry>
<entry align="left" valign="top"><para>UNIX C shell prompt</para></entry>
<entry align="left" valign="top"><para><filename>system%</filename></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>$</filename></para></entry>
<entry align="left" valign="top"><para>UNIX Bourne and Korn shell prompt
</para></entry>
<entry align="left" valign="top"><para><filename>system$</filename></para></entry>
</row>
<row>
<entry align="left" valign="top"><para><filename>#</filename></para></entry>
<entry align="left" valign="top"><para>Superuser prompt, all shells</para></entry>
<entry align="left" valign="top"><para><filename>system#</filename></para></entry>
</row></tbody></tgroup><?Pub Caret></table>
</sect1>
</preface>
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 10:26:11-->
<?Pub *0000010499>