dtksh(1) USER COMMANDS dtksh(1)NAMEdtksh - shell command language interpreter with access to
many X, Xt, Xm and TED functions
SYNOPSISdtksh [-abCefimnuvx] [-o option] [+abCefmnuvx] [+o option]
[command_file [argument...]]
dtksh [-abCefimnuvx] [-o option] [+abCefmnuvx] [+o option]
command_string [command_name [argument...]]
dtksh-s [-abCefimnuvx] [-o option] [+abeCefmnuvx]
[+o option] [argument...]]
DESCRIPTION
The dtksh utility is a version of the KornShell extended to
support:
o Access to many X, Xt and Motif facilities from within
a shell script
o Fully localized shell scripts
o Access to the TED application help system
o Customization of script-based GUI attributes (such as
font and colors) using the TED customization tool
o Response to session-management Save state directives
o Response to window-management Close directives
o Access to most of the TED Desktop Services Message Set
o Access to many of the CDE Data Typing API functions
o Access to the CDE Action API functions
OPTIONS
See sh(1).
OPERANDS
See sh(1).
RESOURCES
The dtksh interpreter has no relevant resources outside of
those that affect the various widgets that can be instan-
tiated from within a dtksh script. Refer to the manual page
of the relevant widget for information on the resources that
apply to that widget.
Unix System LaboratoLast change: 1 August 1995 1
dtksh(1) USER COMMANDS dtksh(1)STDIN
See sh(1).
INPUT FILES
See sh(1).
ENVIRONMENT VARIABLES
The following information describes the environment vari-
ables that dtksh uses that are in addition to those docu-
mented in the manual page for the sh command language inter-
preter.
Immediate Return Value (-)
Many of the category 3 commands (as described in the Return
Values From Built-in Commands section) return a single value
using an environment variable specified as the first argu-
ment to the command (in the synopses for these special com-
mands, the first argument has the name variable). If this
return value is immediately used in an expression, the spe-
cial environment variable ``-'' can be used in place of a
variable name. When dtksh encounters ``-'' as the name of
the environment variable in which the return value is to be
returned, it 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 works only for commands
that return a single value; the value is the first argument
and the argument has the name variable). For example:
XtDisplay DISPLAY $FORM
XSync $DISPLAY true
can be replaced by the equivalent:
XSync $(XtDisplay "-" $FORM) true
The reference to $DISPLAY is replaced with the value
returned by the call to XtDisplay. 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 argument is not named variable. Com-
mands that do not accept ``-'' as the environment variable
name include: XtInitialize, XtCreateApplicationShell,
XtCreatePopupShell, XtCreateManagedWidget and
XtCreateWidget; all commands of the form:
XmCreate...()
and most commands of the form:
tt_...()Unix System LaboratoLast change: 1 August 1995 2
dtksh(1) USER COMMANDS dtksh(1)
Variables Set By XtInitialize
The XtInitialize command sets the following variables:
DTKSH_APPNAME
DTKSH_ARGV
DTKSH_TOPLEVEL
Callback Context Variables
An application registers a callback with a widget to specify
which condition it is interested in, and what action should
occur when that condition occurs. The action can be any
arbitrary dtksh command line. For example:
XtAddCallback $WIDGET activateCallback "ActivateProc"
XtAddCallback $WIDGET activateCallback "XtSetSensitive $BUTTON false"
A callback needs to be passed some context so it can deter-
mine what condition led to its call. For a C procedure,
this information is typically passed in a call_data struc-
ture. For example, a Scale widget invoking a valueChanged-
Callback passes in call_data an instance of the following
structure:
typedef struct {
int reason;
XEvent *event;
int value;
} XmScaleCallbackStruct;
The C application's callback does something like:
if (scaleCallData->reason == XmCR_VALUE_CHANGED) {
eventType = scaleCallData->event->type;
display = scaleCallData->event->xany.display;
}
Similarly in dtksh, when a callback is invoked, the follow-
ing special environment variables are set up before the
callback command executes:
CB_WIDGET
Set to the widget handle for the widget invoking
the callback.
CB_CALL_DATA
Set to the address of the call_data structure
passed by the widget to the callback, but its use-
fulness lies in the nested sub-variables associated
with it.
The CB_CALL_DATA environment variable represents a pointer
to a structure; access to its fields uses a syntax similar
Unix System LaboratoLast change: 1 August 1995 3
dtksh(1) USER COMMANDS dtksh(1)
to the C code. Nested environment variables are defined,
named the same as the fields of the structure (but folded to
all upper case), and use a dot to indicate containment of an
element in a structure. Thus, the preceding C code, to
access the call_data provided by the Scale widget,
translates to:
if [${CB_CALL_DATA.REASON} = "CR_VALUE_CHANGED"]; then
eventType=${CB_CALL_DATA.EVENT.TYPE}
display=${CB_CALL_DATA.EVENT.XANY.DISPLAY}
fi
The same is true of the event structure within the call_data
structure.
For most callback structures, the shell script is able to
reference any of the fields defined for the particular call-
back structure, using the technique previously described in
this manual page. In most cases, the shell script is not
able to alter the values of the fields within these struc-
tures. The exception to this is the XmTextVerifyCallback-
Struct, available during the losingFocusCallback, the
modifyVerifyCallback and the motionVerifyCallback for the
text widget. The dtksh utility 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 can be modified:
CB_CALL_DATA.DOIT
CB_CALL_DATA.STARTPOS
CB_CALL_DATA.ENDPOS
CB_CALL_DATA.TEXT.PTR
CB_CALL_DATA.TEXT.LENGTH
CB_CALL_DATA.TEXT.FORMAT
An example of how these fields can be modified:
CB_CALL_DATA.DOIT="false"
CB_CALL_DATA.TEXT.PTR="*"
CB_CALL_DATA.TEXT.LENGTH=1
Event Handler Context Variables
As with callbacks, an application registers event handlers
with a widget to specify what action should occur when one
of the specified events occurs. Again, the action can be
any arbitrary dtksh command line. For example:
XtAddEventHandler $W "Button2MotionMask" false "ActivateProc"
XtAddEventHandler $W "ButtonPressMask|ButtonReleaseMask" \
false "echo action"
Unix System LaboratoLast change: 1 August 1995 4
dtksh(1) USER COMMANDS dtksh(1)
Just as with callbacks, two environment variables are
defined to provide context to the event handler:
EH_WIDGET
Set to the widget handle for the widget for which
the event handler is registered.
EH_EVENT
Set to the address of the XEvent that triggered the
event handler.
Access to the fields within the XEvent structure is the same
as for the CB_CALL_DATA environment variable previously
described in this manual page. For example:
if [${EH_EVENT.TYPE} = "ButtonPress"]; then
echo X = ${EH_EVENT.XBUTTON.X}
echo Y = ${EH_EVENT.XBUTTON.Y}
elif [${EH_EVENT.TYPE} = "KeyPress"]; then
echo X = ${EH_EVENT.XKEY.X}
echo Y = ${EH_EVENT.XKEY.Y}
fi
Translation Context Variables
Xt provides for event translations to be registered for a
widget; their context is provided in the same way as with
event handlers. The two variables defined for translation
commands are:
TRANSLATION_WIDGET
Set to the widget handle for the widget for which
the translation is registered.
TRANSLATION_EVENT
Set to the address of the XEvent that triggered the
translation.
Dot-notation provides access to the fields of the event:
echo Event type = ${TRANSLATION_EVENT.TYPE}
echo Display = ${TRANSLATION_EVENT.XANY.DISPLAY}
Workspace Callback Context Variables
An application can register a callback function that is
invoked any time the user changes to a new workspace. When
the callback is invoked, the following two special environ-
ment variables are set, and can be accessed by the shell
callback code:
CB_WIDGET
Set to the widget handle for the widget invoking
the callback.
Unix System LaboratoLast change: 1 August 1995 5
dtksh(1) USER COMMANDS dtksh(1)
CB_CALL_DATA
Set to the X atom that uniquely identifies the new
workspace. This can be converted to its string
representation using the XmGetAtomName command.
Accessing Event Subfields
The XEvent structure has many different configurations based
on the event's type. The dtksh utility provides access only
to the most frequently used XEvents. Any of the other stan-
dard XEvents are accessed using the event type XANY, fol-
lowed by any of the subfields defined by the XANY event
structure, which includes the following subfields:
${TRANSLATION_EVENT.XANY.TYPE}
${TRANSLATION_EVENT.XANY.SERIAL}
${TRANSLATION_EVENT.XANY.SEND_EVENT}
${TRANSLATION_EVENT.XANY.DISPLAY}
${TRANSLATION_EVENT.XANY.WINDOW}
The dtksh utility supports full access to all of the event
fields for the following event types:
XANY
XBUTTON
XEXPOSE
XNOEXPOSE
XGRAPHICSEXPOSE
XKEY
XMOTION
The following examples show how the subfields for the previ-
ously listed event types are accessed:
${TRANSLATION_EVENT.XBUTTON.X}
$(CB_CALL_DATA.EVENT.XKEY.STATE}
${EH_EVENT.XGRAPHICSEXPOSE.WIDTH}
Input Context Variables
Xt provides the XtAddInput(3X) facility that allows an
application to register interest in activity on a particular
file descriptor. This generally includes data available for
reading, the file descriptor being ready for writing, and
exceptions on the file descriptor. If programming in C, the
application provides a handler function that is invoked when
the activity occurs. When reading data from the file
descriptor, it is up to the handler to read the data from
the input source and handle character escaping and line con-
tinuations.
The dtksh utility also supports the XtAddInput(3X) facility,
but has limited its functionality to reading data, and has
taken the reading function a step further to make it easier
Unix System LaboratoLast change: 1 August 1995 6
dtksh(1) USER COMMANDS dtksh(1)
for shell programmers to use. By default, when a shell
script registers interest in a file descriptor, dtksh
invokes the shell script's input handler only when a com-
plete line of text has been received. A complete line of
text is defined to be a line terminated either by an unes-
caped <newline> character, or by end-of-file. The input
handler is also called if no data is available and end-of-
file is reached. This gives the handler the opportunity to
use XtRemoveInput(3X) to remove the input source, and to
close the file descriptor.
The advantage of this default behavior is that input
handlers do not need to do escape processing or handle line
continuations. The disadvantage is that it assumes that all
of the input is line-oriented and contains no binary infor-
mation. If the input source does contain binary informa-
tion, or if the input handler wants to read the data from
the input source directly, dtksh also supports a raw input
mode. In raw mode, dtksh does not read any of the data from
the input source. Any time dtksh is notified that input is
available on the input source, it invokes the shell script's
input handler. It then becomes the handler's responsibility
to read the incoming data, to perform any required buffering
and escape processing, and to detect when end-of-file is
reached (so that the input source can be removed and the
file descriptor closed).
Whether the input handler is configured to operate in the
default mode or in raw mode, dtksh sets up several environ-
ment variables before calling the shell script's input
handler. These environment variables provide the input
handler with everything needed to handle the incoming data:
INPUT_LINE
If operating in the default mode, this variable
contains the next complete line of input available
from the input source. If INPUT_EOF is set to
True, there is no data in this buffer. If operat-
ing in raw mode, this environment variable always
contains an empty string.
INPUT_EOF
If operating in the default mode, this variable is
set to False any time INPUT_LINE contains data, and
is set to True when end-of-file is reached. When
end-of-file is reached, the input handler for the
shell script should unregister the input source and
close the file descriptor. If operating in raw
mode, INPUT_EOF is always set to False.
INPUT_SOURCE
Indicates the file descriptor for which input is
Unix System LaboratoLast change: 1 August 1995 7
dtksh(1) USER COMMANDS dtksh(1)
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 it is no longer needed.
INPUT_ID
Indicates the ID returned by XtAddInput when the
input source was originally registered. This
information is needed in order to remove the input
source using XtRemoveInput.
ASYNCHRONOUS EVENTS
Default.
STDOUT
See sh(1).
STDERR
See sh(1).
OUTPUT FILES
None.
EXTENDED DESCRIPTION
The capabilities described here are extensions to those of
the sh command language interpreter. See sh(1). The fol-
lowing subsections give a synopsis of each of the built-in
commands added by dtksh to sh. In general, argument order-
ing and types are the same as for corresponding C pro-
cedures, with exceptions noted. For more detail on the
functionality and arguments of a command, see the standard
documentation for the corresponding X11, Xt, Motif or Desk-
top Services procedure.
In definitions listed in this document, arguments named
variable, variable2, variable3 and so on, indicate that the
shell script must supply the name of an environment vari-
able, into which some value is returned.
All of the Xt commands used to create a new widget require
that the widget class for the new widget be specified. The
widget (or gadget) class name is the standard class name
provided by Motif. For example, the class name for a Motif
pushbutton widget is XmPushButton, while the class name for
the Motif label gadget is XmLabelGadget. Commands that use
their exit status to return a Boolean value (which can be
used directly as part of an if statement) are noted as such.
Arguments enclosed within [] are optional.
Dtksh Built-in Xlib Commands
XBell display volume
Unix System LaboratoLast change: 1 August 1995 8
dtksh(1) USER COMMANDS dtksh(1)
XClearArea display drawable [optional GC arguments] x y
width height exposures
XClearWindow display drawable
XCopyArea display src dest srcX srcY width height destX
destY [optional GC arguments]
XDefineCursor display window cursor
XDrawArc display drawable [optional GC arguments] x y width
height angle1 angle2
XDrawLine display drawable [optional GC arguments] x1 y1 x2
y2
XDrawLines display drawable [-coordinateMode] [optional GC
arguments] x1 y1 x2 y2 [x3 y3 ...]
The coordinateMode operand is either CoordModeOrigin or
CoordModePrevious.
XDrawPoint display drawable [optional GC arguments] x y
XDrawPoints display drawable [-coordinateMode] [optional GC
arguments] x1 y1 [x2 y2 x3 y3 ...]
The coordinateMode operand is either CoordModeOrigin or
CoordModePrevious.
XDrawRectangle display drawable [optional GC arguments] x y
width height
XDrawSegments display drawable [optional GC arguments] x1 y1
x2 y2 [x3 y3 x4 y4 ...]
XDrawString display drawable [optional GC arguments] x y
string
XDrawImageString display drawable [optional GC arguments] x
y string
XFillArc display drawable [optional GC arguments] x y width
height angle1 angle2
XFillPolygon display drawable [-shape] [-coordinateMode]
[optional GC arguments] x1 y1 x2 y2 ...
The shape operand is one of Complex, Convex or Nonconvex,
and where coordinateMode is either CoordModeOrigin or
CoordModePrevious.
Unix System LaboratoLast change: 1 August 1995 9
dtksh(1) USER COMMANDS dtksh(1)
XFillRectangle display drawable [optional GC arguments] x y
width height
XFlush display
XHeightOfScreen variable screen
XRaiseWindow display window
XRootWindowOfScreen variable screen
XSync display discard
The discard operand is either True or False.
XTextWidth variable fontName string
The XTextWidth command differs from the C procedure; it
takes the name of a font instead of a pointer to a font
structure.
XUndefineCursor display window
XWidthOfScreen variable screen
Built-in XtIntrinsic Commands
XtAddCallback widgetHandle callbackName dtksh-command
The callbackName operand is one of the standard Motif or
Xt callback names, with the Xt or Xm prefix omitted; for
example, activateCallback.
XtAddEventHandler widgetHandle eventMask nonMaskableFlag
dtksh-command
The eventMask operand is of the form mask|mask|mask and
the mask component is any of the standard set of XEvent
masks; for example, ButtonPressMask, where nonMaska-
bleFlag is either True or False.
XtAddInput variable [-r] fileDescriptor dtksh-command
The XtAddInput command registers the indicated file
descriptor with the X Toolkit as an alternative input
source (that is, for reading). The input handler for the
shell script is responsible for unregistering the input
source when it is no longer needed, and also to close the
file descriptor. If the -r option is specified (raw
mode), dtksh does not automatically read any of the data
available from the input source; it is up to the speci-
fied dtksh command to read all data. If the -r option is
not specified, the specified dtksh command is invoked
Unix System LaboratoLast change: 1 August 1995 10
dtksh(1) USER COMMANDS dtksh(1)
only when a full line has been read (that is, a line ter-
minated by either an unescaped <newline> character, or
end-of-file) and when end-of-file is reached. The raw
mode is useful for handlers expecting to process non-
textual data, or for handlers not wanting dtksh to
automatically read in a line of data. When end-of-file
is detected, it is the responsibility of the input
handler for the shell script to use XtRemoveInput to
remove the input source, and to close the file descrip-
tor, if necessary. In all cases, several environment
variables are set up for the handler to use. These
include the following:
INPUT_LINE
Empty if raw mode; otherwise, contains
next line to be processed.
INPUT_EOF
Set to True if end-of-file reached; other-
wise, set to False.
INPUT_SOURCE
File descriptor associated with this input
source.
INPUT_ID
ID associated with this input handler;
returned by XtAddInput.
XtAddTimeout variable interval dtksh-command
XtAddWorkProc variable dtksh-command
In dtksh, the dtksh-command is typically a dtksh function
name. Like regular work procedures, this function is
expected to return a value indicating whether the work
procedure wants to be called again, or whether it has
completed its work and can be automatically unregistered.
If the dtksh function returns zero, the work procedure
remains registered; any other value causes the work pro-
cedure to be automatically unregistered.
XtAugmentTranslations widgetHandle translations
XtCreateApplicationShell variable applicationName
widgetClass [resource:value ...]
XtCallCallbacks widgetHandle callbackName
The callbackName operand is one of the standard Motif or
Xt callback names, with the Xt or Xm prefix omitted; for
example, activateCallback.
Unix System LaboratoLast change: 1 August 1995 11
dtksh(1) USER COMMANDS dtksh(1)
XtClass variable widgetHandle
The command returns the name of the widget class associ-
ated with the passed-in widget handle.
XtCreateManagedWidget variable widgetName widgetClass
parentWidgetHandle [resource:value ...]
XtCreatePopupShell variable widgetName widgetClass
parentWidgetHandle [resource:value ...]
XtCreateWidget variable widgetName widgetClass
parentWidgetHandle [resource:value ...]
XtDestroyWidget widgetHandle [widgetHandle ...]
XtDisplay variable widgetHandle
XtDisplayOfObject variable widgetHandle
XtGetValues widgetHandle resource:variable1
[resource:variable2 ...]
XtHasCallbacks variable widgetHandle callbackName
The callbackName operand is one of the standard Motif or
Xt callback names, with the Xt or Xm prefix omitted: for
example, activateCallback variable is set to one of the
strings CallbackNoList, CallbackHasNone or CallbackHas-
Some.
XtInitialize variable shellName applicationClassName appli-
cationName arguments
Similar to a typical Motif-based program, the arguments
argument is used to reference any command-line arguments
that might have been specified by the shell script user;
these are typically referred using the shell syntax of
$@. The applicationName argument is listed because $@
does not include $0. The applicationName and arguments
are used to build the argument list passed to the XtIni-
tialize command. Upon completion, the environment vari-
able DTKSH_ARGV is set to the argument list as returned
by the XtInitialize command; the DTKSH_TOPLEVEL environ-
ment variable is set to the widget handle of the widget
created by XtInitialize, and the DTKSH_APPNAME environ-
ment variable is set to the value of the applicationName
argument. The command returns a value that can be used
in a conditional.
XtIsManaged widgetHandle
Unix System LaboratoLast change: 1 August 1995 12
dtksh(1) USER COMMANDS dtksh(1)
The command returns a value that can be used in a condi-
tional.
XtIsSubclass widgetHandle widgetClass
The widgetClass operand is the name of a widget class.
The command returns a value that can be used in a condi-
tional.
XtNameToWidget variable referenceWidget name
XtIsRealized widgetHandle
The command returns a value that can be used in a condi-
tional.
XtIsSensitive widgetHandle
The command returns a value that can be used in a condi-
tional.
XtIsShell widgetHandle
The command returns a value that can be used in a condi-
tional.
XtLastTimestampProcessed variable display
XtMainLoop
XtManageChild widgetHandle
XtManageChildren widgetHandle [widgetHandle ...]
XtMapWidget widgetHandle
XtOverrideTranslations widgetHandle translations
XtParent variable widgetHandle
XtPopdown widgetHandle
XtPopup widgetHandle grabType
The grabType operand is one of the strings GrabNone,
GrabNonexclusive or GrabExclusive.
XtRealizeWidget widgetHandle
XtRemoveAllCallbacks widgetHandle callbackName
Unix System LaboratoLast change: 1 August 1995 13
dtksh(1) USER COMMANDS dtksh(1)
The callbackName operand is one of the standard Motif or
Xt callback names, with the Xt or Xm prefix omitted; for
example, activateCallback.
XtRemoveCallback widgetHandle callbackName dtksh-command
The callbackName operand is one of the standard Motif or
Xt callback names, with the Xt or Xm prefix omitted; for
example, activateCallback. As with traditional Xt call-
backs, when a callback is removed, the same dtksh command
string must be specified as was specified when the call-
back was originally registered.
XtRemoveEventHandler widgetHandle eventMask nonMaskableFlag
dtksh-command
The eventMask operand is of the form mask|mask|mask and
the mask component is any of the standard set of XEvent
masks; for example, ButtonPressMask, where nonMaska-
bleFlag is either True or False. As with traditional Xt
event handlers, when an event handler is removed, the
same eventMask, nonMaskableFlag setting and dtksh command
string must be specified as was specified when the event
handler was originally registered.
XtRemoveInput inputId
The inputId operand is the handle returned in the speci-
fied environment variable when the alternative input
source was registered using the XtAddInput command.
XtRemoveTimeOut timeoutId
The timeoutId operand is the handle returned in the
specified environment variable when the timeout was
registered using the XtAddTimeOut command.
XtRemoveWorkProc workprocId
The workprocId operand is the handle returned in the
specified environment variable when the work procedure
was registered using the XtAddWorkProc command.
XtScreen variable widgetHandle
XtSetSensitive widgetHandle state
The state operand is either True or False.
XtSetValues widgetHandle resource:value [resource:value ...]
Unix System LaboratoLast change: 1 August 1995 14
dtksh(1) USER COMMANDS dtksh(1)
XtUninstallTranslations widgetHandle
XtUnmanageChild widgetHandle
XtUnmanageChildren widgetHandle [widgetHandle ...]
XtUnmapWidget widgetHandle
XtUnrealizeWidget widgetHandle
XtWindow variable widgetHandle
Built-in Motif Commands
XmAddWMProtocolCallback widgetHandle protocolAtom dtksh-
command
The protocolAtom operand is typically obtained using the
XmInternAtom command.
XmAddWMProtocols widgetHandle protocolAtom [protocolA-
tom ...]
The protocolAtom operand is typically obtained using the
XmInternAtom command.
XmCommandAppendValue widgetHandle string XmCommandError
widgetHandle errorString
XmCommandGetChild variable widgetHandle childType
The childType operand is one of the strings:
DIALOG_COMMAND_TEXT
DIALOG_PROMPT_LABEL
DIALOG_HISTORY_LIST
DIALOG_WORK_AREA
XmCommandSetValue widgetHandle commandString
XmCreateArrowButton variable parentWidgetHandle name
[resource:value ...]
XmCreateArrowButtonGadget variable parentWidgetHandle name
[resource:value ...]
XmCreateBulletinBoard variable parentWidgetHandle name
[resource:value ...]
XmCreateBulletinBoardDialog variable parentWidgetHandle name
[resource:value ...]
Unix System LaboratoLast change: 1 August 1995 15
dtksh(1) USER COMMANDS dtksh(1)
XmCreateCascadeButton variable parentWidgetHandle name
[resource:value ...]
XmCreateCascadeButtonGadget variable parentWidgetHandle name
[resource:value ...]
XmCreateCommand variable parentWidgetHandle name
[resource:value ...]
XmCreateDialogShell variable parentWidgetHandle name
[resource:value ...]
XmCreateDrawingArea variable parentWidgetHandle name
[resource:value ...]
XmCreateDrawnButton variable parentWidgetHandle name
[resource:value ...]
XmCreateErrorDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateFileSelectionBox variable parentWidgetHandle name
[resource:value ...]
XmCreateFileSelectionDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateForm variable parentWidgetHandle name
[resource:value ...]
XmCreateFormDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateFrame variable parentWidgetHandle name
[resource:value ...]
XmCreateInformationDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateLabel variable parentWidgetHandle name
[resource:value ...]
XmCreateLabelGadget variable parentWidgetHandle name
[resource:value ...]
XmCreateList variable parentWidgetHandle name
[resource:value ...]
XmCreateMainWindow variable parentWidgetHandle name
[resource:value ...]
Unix System LaboratoLast change: 1 August 1995 16
dtksh(1) USER COMMANDS dtksh(1)
XmCreateMenuBar variable parentWidgetHandle name
[resource:value ...]
XmCreateMenuShell variable parentWidgetHandle name
[resource:value ...]
XmCreateMessageBox variable parentWidgetHandle name
[resource:value ...]
XmCreateMessageDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateOptionMenu variable parentWidgetHandle name
[resource:value ...]
XmCreatePanedWindow variable parentWidgetHandle name
[resource:value ...]
XmCreatePopupMenu variable parentWidgetHandle name
[resource:value ...]
XmCreatePromptDialog variable parentWidgetHandle name
[resource:value ...]
XmCreatePulldownMenu variable parentWidgetHandle name
[resource:value ...]
XmCreatePushButton variable parentWidgetHandle name
[resource:value ...]
XmCreatePushButtonGadget variable parentWidgetHandle name
[resource:value ...]
XmCreateQuestionDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateRadioBox variable parentWidgetHandle name
[resource:value ...]
XmCreateRowColumn variable parentWidgetHandle name
[resource:value ...]
XmCreateScale variable parentWidgetHandle name
[resource:value ...]
XmCreateScrollBar variable parentWidgetHandle name
[resource:value ...]
XmCreateScrolledList variable parentWidgetHandle name
[resource:value ...]
Unix System LaboratoLast change: 1 August 1995 17
dtksh(1) USER COMMANDS dtksh(1)
XmCreateScrolledText variable parentWidgetHandle name
[resource:value ...]
XmCreateScrolledWindow variable parentWidgetHandle name
[resource:value ...]
XmCreateSelectionBox variable parentWidgetHandle name
[resource:value ...]
XmCreateSelectionDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateSeparator variable parentWidgetHandle name
[resource:value ...]
XmCreateSeparatorGadget variable parentWidgetHandle name
[resource:value ...]
XmCreateText variable parentWidgetHandle name
[resource:value ...]
XmCreateTextField variable parentWidgetHandle name
[resource:value ...]
XmCreateToggleButton variable parentWidgetHandle name
[resource:value ...]
XmCreateToggleButtonGadget variable parentWidgetHandle name
[resource:value ...]
XmCreateWarningDialog variable parentWidgetHandle name
[resource:value ...]
XmCreateWorkArea variable parentWidgetHandle name
[resource:value ...]
XmCreateWorkingDialog variable parentWidgetHandle name
[resource:value ...]
XmFileSelectionDoSearch widgetHandle directoryMask
XmFileSelectionBoxGetChild variable widgetHandle childType
The childType operand is one of the strings:
DIALOG_APPLY_BUTTON
DIALOG_CANCEL_BUTTON
DIALOG_DEFAULT_BUTTON
DIALOG_DIR_LIST
DIALOG_DIR_LIST_LABEL
DIALOG_FILTER_LABEL
DIALOG_FILTER_TEXT
Unix System LaboratoLast change: 1 August 1995 18
dtksh(1) USER COMMANDS dtksh(1)
DIALOG_HELP_BUTTON
DIALOG_LIST
DIALOG_LIST_LABEL
DIALOG_OK_BUTTON
DIALOG_SEPARATOR
DIALOG_SELECTION_LABEL
DIALOG_TEXT
DIALOG_WORK_AREA
XmGetAtomName variable display atom
XmGetColors widgetHandle background variable variable2 vari-
able3 variable4
The XmGetColors command differs from the C procedure in
that it takes a widgetHandle instead of a screen pointer
and a colormap.
XmGetFocusWidget variable widgetHandle
XmGetPostedFromWidget variable widgetHandle
XmGetTabGroup variable widgetHandle
XmGetTearOffControl variable widgetHandle
XmGetVisibility variable widgetHandle
XmInternAtom variable display atomString onlyIfExistsFlag
The onlyIfExistsFlag operand can be set to either True or
False.
XmIsTraversable widgetHandle
The command returns a value that can be used in a condi-
tional.
XmListAddItem widgetHandle position itemString
The ordering of the arguments to the XmListAddItem com-
mand differs from the corresponding C function.
XmListAddItems widgetHandle position itemString [item-
String ...]
The ordering of the arguments to the XmListAddItems com-
mand differs from the corresponding C function.
XmListAddItemsUnselected widgetHandle position itemString
[itemString ...]
Unix System LaboratoLast change: 1 August 1995 19
dtksh(1) USER COMMANDS dtksh(1)
The ordering of the arguments to the XmListAddItemsUn-
selected command differs from the corresponding C func-
tion.
XmListAddItemUnselected widgetHandle position itemString
The ordering of the arguments to the XmListAddItemUn-
selected command differs from the corresponding C func-
tion.
XmListDeleteAllItems widgetHandle
XmListDeleteItem widgetHandle itemString
XmListDeleteItems widgetHandle itemString [itemString ...]
XmListDeleteItemsPos widgetHandle itemCount position
XmListDeletePos widgetHandle position
XmListDeletePositions widgetHandle position [position ...]
XmListDeselectAllItems widgetHandle
XmListDeselectItem widgetHandle itemString
XmListDeselectPos widgetHandle position
XmListGetSelectedPos variable widgetHandle
The command returns in variable a comma-separated list of
indices. The command returns a value that can be used in
a conditional.
XmListGetKbdItemPos variable widgetHandle
XmListGetMatchPos variable widgetHandle itemString
The command returns in variable a comma-separated list of
indices. The command returns a value that can be used in
a conditional.
XmListItemExists widgetHandle itemString
The command returns a value that can be used in a condi-
tional.
XmListItemPos variable widgetHandle itemString
XmListPosSelected widgetHandle position
Unix System LaboratoLast change: 1 August 1995 20
dtksh(1) USER COMMANDS dtksh(1)
The command returns a value that can be used in a condi-
tional.
XmListPosToBounds widgetHandle position variable variable2
variable3 variable4
The command returns a value that can be used in a condi-
tional.
XmListReplaceItemsPos widgetHandle position itemString
[itemString ...]
The ordering of the arguments to the XmListReplaceItem-
sPos command differs from the corresponding C function.
XmListReplaceItemsPosUnselected widgetHandle position item-
String [itemString ...]
The ordering of the arguments to the XmListReplaceItem-
sPosUnselected command differs from the corresponding C
function.
XmListSelectItem widgetHandle itemString notifyFlag
The notifyFlag operand can be set to either True or
False.
XmListSelectPos widgetHandle position notifyFlag
The notifyFlag operand can be set to either True or
False.
XmListSetAddMode widgetHandle state
The state operand can be set to either True or False.
XmListSetBottomItem widgetHandle itemString
XmListSetBottomPos widgetHandle position
XmListSetHorizPos widgetHandle position
XmListSetItem widgetHandle itemString
XmListSetKbdItemPos widgetHandle position
The command returns a value that can be used in a condi-
tional.
XmListSetPos widgetHandle position
Unix System LaboratoLast change: 1 August 1995 21
dtksh(1) USER COMMANDS dtksh(1)
XmListUpdateSelectedList widgetHandle
XmMainWindowSep1 variable widgetHandle
XmMainWindowSep2 variable widgetHandle
XmMainWindowSep3 variable widgetHandle
XmMainWindowSetAreas widgetHandle menuWidgetHandle com-
mandWidgetHandle horizontalScrollbarWidgetHandle vertical-
ScrollbarWidgetHandle workRegionWidgetHandle
XmMenuPosition widgetHandle eventHandle
The eventHandle operand refers to an XEvent that has typ-
ically been obtained by accessing the CB_CALL_DATA.EVENT,
EH_EVENT or TRANSLATION_EVENT environment variables.
XmMessageBoxGetChild variable widgetHandle childType
The childType operand is one of the strings:
DIALOG_CANCEL_BUTTON
DIALOG_DEFAULT_BUTTON
DIALOG_HELP_BUTTON
DIALOG_MESSAGE_LABEL
DIALOG_OK_BUTTON
DIALOG_SEPARATOR
DIALOG_SYMBOL_LABEL
XmOptionButtonGadget variable widgetHandle
XmOptionLabelGadget variable widgetHandle
XmProcessTraversal widgetHandle direction
The direction operand is one of the strings:
TRAVERSE_CURRENT
TRAVERSE_DOWN
TRAVERSE_HOME
TRAVERSE_LEFT
TRAVERSE_NEXT
TRAVERSE_NEXT_TAB_GROUP
TRAVERSE_PREV
TRAVERSE_PREV_TAB_GROUP
TRAVERSE_RIGHT
TRAVERSE_UP
The command returns a value that can be used in a condi-
tional.
Unix System LaboratoLast change: 1 August 1995 22
dtksh(1) USER COMMANDS dtksh(1)
XmRemoveWMProtocolCallback widgetHandle protocolAtom dtksh-
command
The protocolAtom operand is typically obtained using the
XmInternAtom command. As with traditional WM callbacks,
when a callback is removed, the same dtksh command string
must be specified as was specified when the callback was
originally registered.
XmRemoveWMProtocols widgetHandle protocolAtom [protocolA-
tom ...]
The protocolAtom operand is typically obtained using the
XmInternAtom command.
XmScaleGetValue widgetHandle variable
XmScaleSetValue widgetHandle value
XmScrollBarGetValues widgetHandle variable variable2 vari-
able3 variable4
XmScrollBarSetValues widgetHandle value sliderSize increment
pageIncrement notifyFlag
The notifyFlag operand can be set to either True or
False.
XmScrollVisible widgetHandle widgetHandle leftRightMargin
topBottomMargin
XmSelectionBoxGetChild variable widgetHandle childType
The childType operand is one of the strings:
DIALOG_CANCEL_BUTTON
DIALOG_DEFAULT_BUTTON
DIALOG_HELP_BUTTON
DIALOG_APPLY_BUTTON
DIALOG_LIST
DIALOG_LIST_LABEL
DIALOG_OK_BUTTON
DIALOG_SELECTION_LABEL
DIALOG_SEPARATOR
DIALOG_TEXT
DIALOG_WORK_AREA
XmTextClearSelection widgetHandle time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command.
Unix System LaboratoLast change: 1 August 1995 23
dtksh(1) USER COMMANDS dtksh(1)
XmTextCopy widgetHandle time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command. The command returns a value that can be used in
a conditional.
XmTextCut widgetHandle time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command. The command returns a value that can be used in
a conditional.
XmTextDisableRedisplay widgetHandle
XmTextEnableDisplay widgetHandle
XmTextFindString widgetHandle startPosition string direction
variable
The direction operand is one of the strings TEXT_FORWARD
or TEXT_BACKWARD. The command returns a value that can
be used in a conditional.
XmTextGetBaseline variable widgetHandle
XmTextGetEditable widgetHandle
The command returns a value that can be used in a condi-
tional.
XmTextGetInsertionPosition variable widgetHandle
XmTextGetLastPosition variable widgetHandle
XmTextGetMaxLength variable widgetHandle
XmTextGetSelection variable widgetHandle
XmTextGetSelectionPosition widgetHandle variable variable2
The command returns a value that can be used in a condi-
tional.
XmTextGetString variable widgetHandle
XmTextGetTopCharacter variable widgetHandle
XmTextInsert widgetHandle position string
Unix System LaboratoLast change: 1 August 1995 24
dtksh(1) USER COMMANDS dtksh(1)
XmTextPaste widgetHandle
The command returns a value that can be used in a condi-
tional.
XmTextPosToXY widgetHandle position variable variable2
The command returns a value that can be used in a condi-
tional.
XmTextRemove widgetHandle
The command returns a value that can be used in a condi-
tional.
XmTextReplace widgetHandle fromPosition toPosition string
XmTextScroll widgetHandle lines
XmTextSetAddMode widgetHandle state
The state operand can be set to either True or False.
XmTextSetEditable widgetHandle editableFlag
The editableFlag operand can be set to either True or
False.
XmTextSetHighlight widgetHandle leftPosition rightPosition
mode
The mode operand is one of the strings:
HIGHLIGHT_NORMAL
HIGHLIGHT_SELECTED
HIGHLIGHT_SECONDARY_SELECTED
XmTextSetInsertionPosition widgetHandle position
XmTextSetMaxLength widgetHandle maxLength
XmTextSetSelection widgetHandle firstPosition lastPosition
time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command.
XmTextSetString widgetHandle string
XmTextSetTopCharacter widgetHandle topCharacterPosition
Unix System LaboratoLast change: 1 August 1995 25
dtksh(1) USER COMMANDS dtksh(1)
XmTextShowPosition widgetHandle position
XmTextXYToPos variable widgetHandle x y
XmTextFieldClearSelection widgetHandle time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command.
XmTextFieldGetBaseline variable widgetHandle
XmTextFieldGetEditable widgetHandle
The command returns a value that can be used in a condi-
tional.
XmTextFieldGetInsertionPosition variable widgetHandle
XmTextFieldGetLastPosition variable widgetHandle
XmTextFieldGetMaxLength variable widgetHandle
XmTextFieldGetSelection variable widgetHandle
XmTextFieldGetSelectionPosition widgetHandle variable vari-
able2
The command returns a value that can be used in a condi-
tional.
XmTextFieldGetString variable widgetHandle
XmTextFieldInsert widgetHandle position string
XmTextFieldPosToXY widgetHandle position variable variable2
The command returns a value that can be used in a condi-
tional.
XmTextFieldRemove widgetHandle
The command returns a value that can be used in a condi-
tional.
XmTextFieldReplace widgetHandle fromPosition toPosition
string
XmTextFieldSetEditable widgetHandle editableFlag
The editableFlag operand can be set to either True or
False.
Unix System LaboratoLast change: 1 August 1995 26
dtksh(1) USER COMMANDS dtksh(1)
XmTextFieldSetHighlight widgetHandle leftPosition rightPosi-
tion mode
The mode operand is one of the strings:
HIGHLIGHT_NORMAL
HIGHLIGHT_SELECTED
HIGHLIGHT_SECONDARY_SELECTED
XmTextFieldSetInsertionPosition widgetHandle position
XmTextFieldSetMaxLength widgetHandle maxLength
XmTextFieldSetSelection widgetHandle firstPosition lastPosi-
tion time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command.
XmTextFieldSetString widgetHandle string
XmTextFieldShowPosition widgetHandle position
XmTextFieldXYToPos variable widgetHandle x y
XmTextFieldCopy widgetHandle time
The time operand is typically either obtained from within
an XEvent, or from a call to the XtLastTimestampProcessed
command. The command returns a value that can be used in
a conditional.
XmTextFieldCut widgetHandle time
The time operand is typically either obtained from within
an XEvent or from a call to the XtLastTimestampProcessed
command. The command returns a value that can be used in
a conditional.
XmTextFieldPaste widgetHandle
The command returns a value that can be used in a condi-
tional.
XmTextFieldSetAddMode widgetHandle state
The state operand can be set to either True or False.
XmToggleButtonGadgetGetState widgetHandle
Unix System LaboratoLast change: 1 August 1995 27
dtksh(1) USER COMMANDS dtksh(1)
The command returns a value that can be used in a condi-
tional.
XmToggleButtonGadgetSetState widgetHandle state notifyFlag
The state operand can be set to either True or False.
The notifyFlag operand can be set to either True or
False.
XmToggleButtonGetState widgetHandle
The command returns a value that can be used in a condi-
tional.
XmToggleButtonSetState widgetHandle state notifyFlag
The state operand can be set to either True or False.
The notifyFlag operand can be set to either True or
False.
XmUpdateDisplay widgetHandle
Built-in TED Application Help Commands
DtCreateHelpQuickDialog variable parentWidgetHandle name
[resource:value ...]
DtCreateHelpDialog variable parentWidgetHandle name
[resource:value ...]
DtHelpQuickDialogGetChild variable widgetHandle childType
The childType operand is one of the strings:
HELP_QUICK_OK_BUTTON
HELP_QUICK_PRINT_BUTTON
HELP_QUICK_HELP_BUTTON
HELP_QUICK_SEPARATOR
HELP_QUICK_MORE_BUTTON
HELP_QUICK_BACK_BUTTON
DtHelpReturnSelectedWidgetId variable widgetHandle variable2
The variable operand is set to one of the strings:
HELP_SELECT_VALID
HELP_SELECT_INVALID
HELP_SELECT_ABORT
HELP_SELECT_ERROR
and variable2 is set to the widgetHandle for the selected
widget.
Unix System LaboratoLast change: 1 August 1995 28
dtksh(1) USER COMMANDS dtksh(1)
DtHelpSetCatalogName catalogName
Built-in Localization Commands
catopen variable catalogName
Opens the indicated message catalog, and returns the
catalog ID in the environment variable specified by vari-
able. If a shell script needs to close the file descrip-
tor associated with a message catalog, the catalog ID
must be closed using the catclose command.
catgets variable catalogId setNumber messageNumber default-
MessageString
Attempts to extract the requested message string from the
message catalog associated with the catalogId argument.
If the message string cannot be located, the default mes-
sage string is returned. In either case, the returned
message string is placed into the environment variable
indicated by variable.
catclose catalogId
Closes the message catalog associated with the indicated
catalogId.
Built-in Session Management Commands
DtSessionRestorePath widgetHandle variable sessionFile
Given the filename for the session file (excluding any
path information), this command returns the full pathname
for the session file in the environment variable indi-
cated by variable. The command returns a value that can
be used in a conditional, indicating whether the command
succeeded.
DtSessionSavePath widgetHandle variable variable2
The full pathname for the session file is returned in
environment variable indicated by variable. The filename
portion of the session file (excluding any path informa-
tion) is returned in the environment variable indicated
by variable2. The command returns a value that can be
used in a conditional, indicating whether the command
succeeded.
DtShellIsIconified widgetHandle
The command returns a value that can be used in a condi-
tional.
Unix System LaboratoLast change: 1 August 1995 29
dtksh(1) USER COMMANDS dtksh(1)
DtSetStartupCommand widgetHandle commandString
Part of the session management process is telling the
session manager how to restart the application the next
time the user reopens the session. This command passes
along the specified command string to the session
manager. The widget handle should refer to an applica-
tion shell.
DtSetIconifyHint widgetHandle iconifyHint
The iconifyHint operand can be set to either True or
False. This command sets the initial iconified state for
a shell window. This command only works if the window
associated with the widget has not yet been realized.
Built-in Workspace Management Commands
DtWsmAddCurrentWorkspaceCallback variable widgetHandle
dtksh-command
This command evaluates the specified dtksh command when-
ever the user changes workspaces. The handle associated
with this callback is returned in the environment vari-
able indicated by variable. The widget indicated by
widgetHandle should be a shell widget.
DtWsmRemoveWorkspaceCallback callback-handle
The callback-handle must be a handle that was returned by
DtWsmAddCurrentWorkspaceCallback.
DtWsmGetCurrentWorkspace display rootWindow variable
This command returns the X atom representing the user's
current workspace in the environment variable indicated
by variable. The XmGetAtomName command maps the X atom
into its string representation.
DtWsmSetCurrentWorkspace widgetHandle workspaceNameAtom
This command changes the user's current workspace to the
workspace indicated by workspaceNameAtom. The command
returns a value that can be used in a conditional, indi-
cating whether the command succeeded.
DtWsmGetWorkspaceList display rootWindow variable
This command returns in variable a string of comma-
separated X atoms, representing the current set of
workspaces defined for the user. The command returns a
value that can be used in a conditional, indicating
whether the command succeeded.
Unix System LaboratoLast change: 1 August 1995 30
dtksh(1) USER COMMANDS dtksh(1)
DtWsmGetWorkspacesOccupied display window variable
This command returns a string of comma-separated X atoms,
representing the current set of workspaces occupied by
the indicated shell window in the environment variable
indicated by variable. The command returns a value that
can be used in a conditional, indicating whether the com-
mand succeeded.
DtWsmSetWorkspacesOccupied display window workspaceList
This command moves the indicated shell window to the set
of workspaces indicated by the string workspaceList,
which must be a comma-separated list of X atoms.
DtWsmAddWorkspaceFunctions display window
DtWsmRemoveWorkspaceFunctions display window
DtWsmOccupyAllWorkspaces display window
DtWsmGetCurrentBackdropWindows display rootWindow variable
This command returns in variable a string of comma-
separated window IDs representing the set of root back-
drop windows.
Built-in Action Commands
The set of commands in this section provides the programmer
with the tools for loading the action databases, querying
information about actions defined in the databases, and
requesting that an action be initiated.
DtDbLoad
This command reads in the action and data types data-
bases. It must be called before any of the other Action
or Data Typing Commands. The shell script should also
use the DtDbReloadNotify command so that the shell script
can be notified if new databases must be loaded.
DtDbReloadNotify dtksh-command
The specified dtksh command is executed when the notifi-
cation is received. Typically, the dtksh command
includes a call to the DtDbLoad command.
DtActionExists actionName
The command returns a value that can be used in a condi-
tional.
Unix System LaboratoLast change: 1 August 1995 31
dtksh(1) USER COMMANDS dtksh(1)
DtActionLabel variable actionName
If the action does not exist, then an empty string is
returned.
DtActionDescription variable actionName
This command returns an empty string if the action is not
defined, or if the DESCRIPTION attribute is not speci-
fied.
DtActionInvoke widgetHandle actionName termOpts execHost
contextDir useIndicator dtksh-command [FILE fileName] ...
The [FILE fileName] couplets can be used to specify file
arguments to be used by DtActionInvoke when invoking the
specified action. The dtksh-command argument is not sup-
ported in TED, and should be specified as a null ("")
value.
Built-in Data Typing Commands
DtDtsLoadDataTypes
This command should be invoked before any of the other
data typing commands.
DtDtsFileToDataType variable filePath
This command returns the name of the data type associated
with the file indicated by the filePath argument in the
variable argument. The variable argument is set to an
empty string if the file cannot be typed.
DtDtsFileToAttributeValue variable filePath attrName
This command returns the string representing the value of
the specified attribute for the data type associated with
the indicated file in the variable argument. If the
attribute is not defined, or if the file cannot be typed,
the variable argument is set to an empty string.
DtDtsFileToAttributeList variable filePath
This command returns the space-separated list of attri-
bute names defined for the data type associated with the
indicated file in the variable argument. A shell script
queries the individual values for the attributes using
the DtDtsFileToAttributeValue command. The variable
argument is set to an empty string if the file cannot be
typed. This command differs from the corresponding C
function in that it only returns the names of the defined
attributes and not their values.
Unix System LaboratoLast change: 1 August 1995 32
dtksh(1) USER COMMANDS dtksh(1)
DtDtsDataTypeToAttributeValue variable dataType attrName
optName
This command returns the string representing the value of
the specified attribute for the indicated data type in
variable. If the attribute is not defined, or if the
indicated data type does not exist, the variable argument
is set to an empty string.
DtDtsDataTypeToAttributeList variable dataType optName
This command returns the space-separated list of attri-
bute names defined for the indicated data type in vari-
able. A shell script queries the individual values for
the attributes using the DtDtsDataTypeToAttributeValue
command. The variable argument is set to an empty string
if the data type is not defined. This command differs
from the corresponding C function in that it only returns
the names of the defined attributes, and not their
values.
DtDtsFindAttribute variable name value
This command returns a space-separated list of data type
names whose attribute, indicated by the name argument,
has the value indicated by the value argument. If an
error occurs, the variable argument is set to an empty
string.
DtDtsDataTypeNames variable
This command returns a space-separated list representing
all of the data types currently defined in the data types
database. If an error occurs, the variable argument is
set to an empty string.
DtDtsSetDataType variable filePath dataType override
The variable argument is set to the resultant saved data
type for the directory.
DtDtsDataTypeIsAction dataType
The command returns a value that can be used in a condi-
tional.
Built-in TED Desktop Services Message Set Commands
The following set of commands implement a subset of the
Desktop Services Message Set, allowing shell script partici-
pation in the Desktop Services protocol. Many of the Tool-
Talk commands differ slightly from their associated C pro-
gramming call. For ToolTalk commands that typically return
Unix System LaboratoLast change: 1 August 1995 33
dtksh(1) USER COMMANDS dtksh(1)
a pointer, a C application can validate that pointer by cal-
ling the tt_ptr_error() function; this C function call
returns a Tt_status value, which indicates whether the
pointer was valid, and if not, why it was not. In dtksh,
all of the Desktop Services Message Set Commands that return
a pointer also return the associated Tt_status value for the
pointer automatically; this saves the shell script from
needing to make an additional call to check the validity of
the original pointer. In the case of a pointer error occur-
ring, dtksh returns an empty string for the pointer value,
and sets the Tt_status code accordingly. The Tt_status
value is returned in the status argument. The Tt_status
value is a string representing the error, and can assume any
of the values shown in the manual page for <Tt/tt_c.h>.
Some of the commands take a message scope as an argument.
For these commands, the scope argument can be set to a
string representing any of the constants documented for
tt_message_scope(1), and in the manual pages for the indivi-
dual ToolTalk functions.
tt_file_netfile variable status file name
tt_netfile_file variable status netfile name
tt_host_file_netfile variable status host file name
tt_host_netfile_file variable status host netfile name
ttdt_open variable status variable2 toolname vendor version
sendStarted
This command returns in the variable argument the procId
associated with the connection. It returns the file
descriptor associated with the connection in variable2;
this file descriptor can be used in registering an alter-
native Xt input handler via the XtAddInput command. The
sendStarted argument is True or False. Any procIds
returned by ttdt_open contain embedded spaces. To
prevent dtksh from interpreting the procId as multiple
arguments (versus a single argument with embedded
spaces), references to the environment variable contain-
ing the procId must be within double quotes, as shown:
ttdt_close STATUS "$PROC_ID" "" True
tttk_Xt_input_handler procId source id
In order for the ToolTalk messages to be received and
processed, the shell script must register an Xt input
handler for the file descriptor returned by the call to
ttdt_open. The Xt input handler is registered using the
Unix System LaboratoLast change: 1 August 1995 34
dtksh(1) USER COMMANDS dtksh(1)
XtAddInput command, and the handler must be registered as
a raw input handler. The input handler that the shell
script registers should invoke tttk_Xt_input_handler to
get the message received and processed. The following
code block demonstrates how this is done:
ttdt_open PROC_ID STATUS FID "Tool" "HP" "1.0" True
XtAddInput INPUT_ID -r $FID "ProcessTTInput \"$PROC_ID\""
ProcessTTInput()
{
tttk_Xt_input_handler $1 $INPUT_SOURCE $INPUT_ID
}
Refer to the description of the XtAddInput command
for more details about alternative Xt input
handlers. This command can be specified as an
alternative Xt input handler, using the XtAddInput
command. The procId value should be that which was
returned by the ttdt_open command. When register-
ing tttk_Xt_input_handler as an alternative Xt
input handler, it must be registered as a raw
handler to prevent dtksh from automatically break-
ing up the input into lines. This can be done as
follows:
XtAddInput returnId -r $tt_fd \
"tttk_Xt_input_handler \"$procId\""
The \" characters before and after the reference to
the procId environment variable are necessary to
protect the embedded spaces in the procId environ-
ment variable.
ttdt_close status procId newProcId sendStopped
This command closes the indicated communications connec-
tion, and optionally sends a Stopped notice, if the
sendStopped argument is set to True. Because the procId
returned by the call to ttdt_open contains embedded
spaces, it must be enclosed within double quotes, as
shown:
ttdt_close STATUS "$PROC_ID" "$NEW_PROC_ID" False
ttdt_session_join variable status sessId shellWidgetHandle
join
This command joins the session indicated by the sessId
argument. If the sessId argument does not specify a
value (that is, it is an empty string), then the default
session is joined. If the shellWidgetHandle argument
specifies a widget handle (that is, it is not an empty
Unix System LaboratoLast change: 1 August 1995 35
dtksh(1) USER COMMANDS dtksh(1)
string), then it should refer to a mappedWhenManaged
applicationShellWidget. The join argument is True or
False. This command returns an opaque pattern handle in
the variable argument; this handle can be destroyed using
the ttdt_session_quit command when it is no longer
needed.
ttdt_session_quit status sessId sessPatterns quit
This command destroys the message patterns specified by
the sessPatterns argument, and, if the quit argument is
set to True, it quits the session indicated by the sessId
argument, or it quits the default session if sessId is
empty.
ttdt_file_join variable status pathName scope join dtksh-
command
An opaque pattern handle is returned in the variable
argument; this should be destroyed by calling
ttdt_file_quit when there is no interest in monitoring
messages for the indicated file. The requested dtksh-
command is evaluated any time a message is received for
the indicated file. When this dtksh-command is
evaluated, the following environment variables are
defined, and provide additional information about the
received message:
DT_TT_MSG
The opaque handle for the incoming mes-
sage.
DT_TT_OP
The string representing the operation to
be performed; that is, TTDT_DELETED,
TTDT_MODIFIED, TTDT_REVERTED, TTDT_MOVED
or TTDT_SAVED.
DT_TT_PATHNAME
The pathname for the file to which this
message pertains.
DT_TT_SAME_EUID_EGID
Set to True if the message was sent by an
application operating with the same effec-
tive user ID and effective group ID as
this process.
DT_TT_SAME_PROCID
Set to True if the message was sent by an
application with the same procId (as
returned by ttdt_open).
Unix System LaboratoLast change: 1 August 1995 36
dtksh(1) USER COMMANDS dtksh(1)
When the callback completes, it must indicate
whether the passed-in message was consumed
(replied-to, failed or rejected). If the callback
returns the message (as passed in the DT_TT_MSG
environment variable), it is assumed that the mes-
sage was not consumed. If the message was con-
sumed, the callback should return zero, or one of
the values returned by the tt_error_pointer com-
mand. The callback can return its value in the
following fashion:
return $DT_TT_MSG (or) return 0
ttdt_file_quit status patterns quit
This command destroys the message patterns specified by
the patterns argument, and also unregisters interest in
the pathname that was passed to the ttdt_file_join com-
mand if quit is set to True; the patterns argument should
be the value returned by a call to the ttdt_file_join
command.
ttdt_file_event status op patterns send
This command creates, and optionally sends, a ToolTalk
notice announcing an event pertaining to a file. The
file is indicated by the pathname passed to the
ttdt_file_join command when patterns was created. The op
argument indicates what should be announced for the indi-
cated file, and can be set to TTDT_MODIFIED, TTDT_SAVED
or TTDT_REVERTED. If op is set to TTDT_MODIFIED, this
command registers to handle Get_Modified, Save and Revert
messages in the scope specified when the patterns was
created. If op is set to TTDT_SAVED or TTDT_REVERTED,
this command unregisters from handling Get_Modified, Save
and Revert messages for this file. If the send argument
is set to True, the indicated message is sent.
ttdt_Get_Modified pathName scope timeout
This commands sends a Get_Modified request in the indi-
cated scope, and waits for a reply, or for the specified
timeout (in milliseconds) to elapse. It returns a value
that can be used in a conditional. A value of True is
returned if an affirmative reply is received within the
specified timeout; otherwise, False is returned.
ttdt_Save status pathName scope timeout
This command sends a Save request in the indicated scope,
and waits for a reply, or for the indicated timeout (in
milliseconds) to elapse. A status of TT_OK is returned
Unix System LaboratoLast change: 1 August 1995 37
dtksh(1) USER COMMANDS dtksh(1)
if an affirmative reply is received before the timeout
elapses; otherwise, a Tt_status error value is returned.
ttdt_Revert status pathName scope timeout
This command sends a Revert request in the indicated
scope, and waits for a reply, or for the indicated
timeout (in milliseconds) to elapse. A status of TT_OK
is returned if an affirmative reply is received before
the timeout elapses; otherwise, a Tt_status error value
is returned.
The following commands are typically used by the callback
registered with the ttdt_file_join command. They serve as
the mechanism for consuming and destroying a message. A
message is consumed by either rejecting, failing or replying
to it. The tt_error_pointer is used by the callback to get
a return pointer for indicating an error condition.
tt_error_pointer variable ttStatus
This command returns a magic value, which is used by
ToolTalk to represent an invalid pointer. The magic
value returned depends on the ttStatus value passed in.
Any of the valid Tt_status values can be specified.
tttk_message_destroy status msg
This command destroys any patterns that may have been
stored on the message indicated by the msg argument, and
then it destroys the message.
tttk_message_reject status msg msgStatus msgStatusString
destroy
This command sets the status and the status string for
the indicated request message, and then rejects the mes-
sage. It then destroys the passed-in message if the des-
troy argument is set to True. This command is one way in
which the callback specified with the ttdt_file_join com-
mand consumes a message. After rejecting the message, it
is typically safe to destroy the message using
tttk_message_destroy.
tttk_message_fail status msg msgStatus msgStatusString des-
troy
This command sets the status and the status string for
the indicated request message, and then it fails the mes-
sage. It destroys the passed-in message if the destroy
argument is set to True. This command is one way in
which the callback specified with the ttdt_file_join
Unix System LaboratoLast change: 1 August 1995 38
dtksh(1) USER COMMANDS dtksh(1)
command consumes a message. After failing the message,
it is typically safe to destroy the message, using
tttk_message_destroy.
tt_message_reply status msg
This command informs the ToolTalk service that the shell
script has handled the message specified by the msg argu-
ment. After replying to a message, it is typically safe
to destroy the message using the tttk_message_destroy
command.
Listing Widget Information
The DtWidgetInfo command provides the shell programmer a
mechanism for obtaining information about the current set of
instantiated widgets and their resources; the information is
written to the standard output. This provides useful debug-
ging information by including:
o The list of instantiated widgets, including: the
name, class and parent of the widget; a handle for the
widget; the name of the environment variable supplied
when the widget was created; the state of the widget.
o The list of resources supported by a particular widget
class.
o The list of constraint resources supported by a par-
ticular widget class.
DtWidgetInfo is called by using any of the following syn-
taxes; all of the arguments are optional:
DtWidgetInfo [widgetHandle | widgetName]
If no arguments are supplied, information about all
existing widgets is written to standard output; the
information includes the name, the handle, the environ-
ment variable, the parent, the widget class and the
state. If arguments are supplied, they should be either
widget handles, or the names of existing widgets; in this
case, the information is written only for the requested
set of widgets.
DtWidgetInfo -r [widgetHandle | widgetClass]
If no arguments are supplied, the list of supported
resources is written to standard output for all available
widget classes. If arguments are supplied, they should
be either widget handles, or the widget class names; in
this case, the information is written only for the
requested set of widgets or widget classes.
Unix System LaboratoLast change: 1 August 1995 39
dtksh(1) USER COMMANDS dtksh(1)
DtWidgetInfo -R [widgetHandle | widgetClass]
If no arguments are supplied, the list of supported con-
straint resources, if any, is written to standard output
for all available widget classes. If arguments are sup-
plied, they should be either widget handles, or the
widget class names; in this case, the information is
written only for the requested set of widgets or widget
classes.
DtWidgetInfo -c [widgetClass]
If no arguments are supplied, the list of supported
widget class names is written to standard output. If
arguments are supplied, dtksh writes the widget class
name (if it is defined); otherwise, it writes an error
message to standard error.
DtWidgetInfo -h [widgetHandle]
If no arguments are supplied, the list of active widget
handles is written to standard output. If arguments are
supplied, they should represent widget handles, in which
case the name of the associated widget is written to
standard output.
Convenience Functions
The TED system includes a file of dtksh convenience func-
tions. This file is itself a shell script containing shell
functions that may be useful to a shell programmer. The
shell functions perform frequently used operations. These
include functions for quickly creating certain kinds of dia-
logs (help, error, warning and so on), and 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.
Before a shell script can access these functions, the shell
script must first include the file containing the conveni-
ence functions. The convenience functions are located in
the file /usr/dt/lib/dtksh/DtFuncs.dtsh, and are included in
a shell script using the following notation:
. /usr/dt/lib/dtksh/DtFuncs.dtsh
DtkshAddButtons
This convenience function adds one or more buttons of the
same kind into a composite widget. Most frequently, it is
used to add a collection of buttons into a menupane or
Unix System LaboratoLast change: 1 August 1995 40
dtksh(1) USER COMMANDS dtksh(1)
menubar.
DtkshAddButtons parent widgetClass label1 callback1 [label2
callback2 ...]
DtkshAddButtons [-w] parent widgetClass variable1 label1
callback1 [variable2 label2 callback2 ...]
The -w 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 widgetClass argument can be set to any one of
the following, and defaults to XmPushButtonGadget, if not
specified:
XmPushButton
XmPushButtonGadget
XmToggleButton
XmToggleButtonGadget
XmCascadeButton
XmCascadeButtonGadget
Examples:
DtkshAddButtons $MENU XmPushButtonGadget Open do_Open Save \
do_Save Quit exit
DtkshAddButtons -w $MENU XmPushButtonGadget B1 Open \
do_Open B2 Save do_Save
DtkshSetReturnKeyControls
This convenience function configures a text widget (within a
form widget), so the <carriage-return> key does not activate
the default button within the form. Instead, the
<carriage-return> key moves the focus to the next text
widget within the form. This is useful if a window, con-
taining a series of text widgets and the default button,
should not be activated until the user presses the
<carriage-return> key while the focus is in the last text
widget.
DtkshSetReturnKeyControls textWidget nextTextWidget
formWidget defaultButton
The textWidget argument specifies the widget to be config-
ured so it catches the <carriage-return> key, and forces the
focus to move to the next text widget (as indicated by the
nextTextWidget argument). The formWidget argument specifies
the form containing the default button, and must be the
parent of the two text widgets. The defaultButton argument
indicates which component to treat as the default button
within the form widget.
Unix System LaboratoLast change: 1 August 1995 41
dtksh(1) USER COMMANDS dtksh(1)
Examples:
DtkshSetReturnKeyControls $TEXT1 $TEXT2 $FORM $OK
DtkshSetReturnKeyControls $TEXT2 $TEXT3 $FORM $OK
DtkshUnder, DtkshOver, DtkshRightOf, DtkshLeftOf
These convenience functions simplify the specification of
certain classes of form constraints. They provide a con-
venient 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
ATTACH_WIDGET constraint.
DtkshUnder widgetId [offset]
DtkshOver widgetId [offset]
DtkshRightOf widgetId [offset]
DtkshLeftOf widgetId [offset]
The widgetId argument specifies the widget to which the
current component is to be attached. The offset value is
optional, and defaults to zero, if not specified.
Example:
XtCreateManagedWidget BUTTON4 button4 pushButton $FORM \
labelString:"Exit" $(DtkshUnder $BUTTON2) \
$(DtkshRightOf $BUTTON3)
DtkshFloatRight, DtkshFloatLeft, DtkshFloatTop, DtkshFloatBot-
tom
These convenience functions simplify the specification of
certain classes of form constraints. They provide a con-
venient 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 on the other form constraints specified for the
component. This behavior is accomplished using the
ATTACH_POSITION constraint.
DtkshFloatRight [position]
DtkshFloatLeft [position]
DtkshFloatTop [position]
DtkshFloatBottom [position]
Unix System LaboratoLast change: 1 August 1995 42
dtksh(1) USER COMMANDS dtksh(1)
The optional position argument specifies the relative posi-
tion to which the indicated edge of the component is posi-
tioned. A default position is used, if one is not speci-
fied.
Example:
XtCreateManagedWidgetBUTTON1 button1 pushButton \
$FORM labelString:"Ok" $(DtkshUnder $SEPARATOR) \
$(DtkshFloatLeft 10) $(DtkshFloatRight 40)
DtkshAnchorRight, DtkshAnchorLeft, DtkshAnchorTop, DtkshAnchor-
Bottom
These convenience functions simplify the specification of
certain classes of form constraints. They provide a con-
venient way of attaching a component to one of the edges of
a form widget in such a fashion that, as the form grows or
shrinks, the component's position does not change. However,
depending on the other form constraints set on this com-
ponent, the component may still grow or shrink in size.
This behavior is accomplished using the ATTACH_FORM con-
straint.
DtkshAnchorRight [offset]
DtkshAnchorLeft [offset]
DtkshAnchorTop [offset]
DtkshAnchorBottom [offset]
The optional offset argument specifies how far from the edge
of the form widget the component should be positioned. If
an offset is not specified, zero is used.
Example:
XtCreateManagedWidget BUTTON1 button1 pushButton \
$FORM labelString:"Ok" $(DtkshUnder $SEPARATOR) \
$(DtkshAnchorLeft 10) $(DtkshAnchorBottom 10)
DtkshSpanWidth, DtkshSpanHeight
These convenience functions simplify the specification of
certain classes of form constraints. They provide a con-
venient way of configuring a component such that it spans
either the full height or width of the form widget. This
behavior is accomplished by attaching two edges of the com-
ponent (top and bottom for DtkshSpanHeight, and left and
right for DtkshSpanWidth) to the form widget. The component
typically resizes whenever the form widget is resized. The
ATTACH_FORM constraint is used for all attachments.
Unix System LaboratoLast change: 1 August 1995 43
dtksh(1) USER COMMANDS dtksh(1)
DtkshSpanWidth [leftOffset rightOffset]
DtkshSpanHeight [topOffset bottomOffset]
The optional offset arguments specify how far from the edges
of the form widget the component should be positioned. If
an offset is not specified, zero is used.
Example:
XtCreateManagedWidget SEP sep separator $FORM $(DtkshSpanWidth 1 1)
DtkshDisplayInformationDialog, DtkshDisplayQuestionDialog,
DtkshDisplayWarningDialog, DtkshDisplayWorkingDialog,
DtkshDisplayErrorDialog
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, it is reused. The
parent of the dialog is obtained from the environment vari-
able, TOPLEVEL, 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:
DTKSH_ERROR_DIALOG_HANDLE
DTKSH_QUESTION_DIALOG_HANDLE
DTKSH_WORKING_DIALOG_HANDLE
DTKSH_WARNING_DIALOG_HANDLE
DTKSH_INFORMATION_DIALOG_HANDLE
When attaching callbacks to the dialog buttons, the applica-
tion should not destroy the dialog; it should simply
unmanage the dialog so that it can be used again later. If
it is necessary to destroy the dialog, the associated
environment variable should also be cleared, so the conveni-
ence function does not attempt to reuse the dialog.
DtkshDisplay*Dialog title message [okCallback closeCallback
\ helpCallback dialogStyle]
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 dialogStyle argu-
ment accepts any of the standard resource settings supported
by the associated bulletin board resource.
Example:
DtkshDisplayErrorDialog "Read Error" "Unable to read the file" \
"OkCallback" "CancelCallback" "" DIALOG_PRIMARY_APPLICATION_MODAL
Unix System LaboratoLast change: 1 August 1995 44
dtksh(1) USER COMMANDS dtksh(1)
DtkshDisplayQuickHelpDialog, DtkshDisplayHelpDialog
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, it is reused. The parent of
the dialog is obtained from the environment variable,
TOPLEVEL, 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:
DTKSH_HELP_DIALOG_HANDLE
DTKSH_QUICK_HELP_DIALOG_HANDLE
If it is necessary to destroy a help dialog, the application
should also clear the associated environment variable, so
that the convenience function does not attempt to reuse the
dialog.
DtkshDisplay*HelpDialog title helpType helpInformation
[locationId]
The meaning of the arguments depends on the value specified
for the helpType argument. The meanings are explained in
the following table:
helpType helpInformation locationId
____________________________________________________________________
HELP_TYPE_DYNAMIC_STRING help string <not used>
HELP_TYPE_FILE help file name <not used>
HELP_TYPE_MAN_PAGE manual page name <not used>
HELP_TYPE_STRING help string <not used>
HELP_TYPE_TOPIC help volume name help topic location ID
____________________________________________________________________
Example:
DtkshDisplayHelpDialog "Help On Dtksh" HELP_TYPE_FILE "helpFileName"
Dtksh App-Defaults File
The dtksh app-defaults file, named dtksh, is in a location
based on the following path description:
/usr/dt/app-defaults/<LANG>
The only information contained in this app-defaults file is
the inclusion of the standard desktop base app-defaults
file. The contents of the dtksh app-defaults file is as
follows:
#include "Dt"
Non-String Values
The C bindings of the interfaces to X, Xt and Motif include
Unix System LaboratoLast change: 1 August 1995 45
dtksh(1) USER COMMANDS dtksh(1)
many non-string values defined in headers. For example, the
constraint values for a child of a form widget are declared,
such as XmATTACH_FORM, with an Xt or Xm prefix followed by a
descriptive name. Equivalent values are specified in dtksh
by omitting the prefix, just as in an app-defaults file.
For example: XmDIALOG_COMMAND_TEXT becomes
DIALOG_COMMAND_TEXT; XtATTACH_FORM becomes ATTACH_FORM.
A Boolean value can be specified as an argument to a dtksh
command using the words True or False; case is not signifi-
cant.
Return Values From Built-in Commands
Graphical commands in dtksh fall into one of four
categories, based on the definition of the corresponding C
function in a windowing library:
1. The function returns no values. Example:
XtMapWidget.
2. The function is void, but returns one or more values
through reference arguments. Example: XmGetColors.
3. The function returns a non-Boolean value. Example:
XtCreateManagedWidget.
4. The function returns a Boolean value. Example:
XtIsSensitive.
A category 1 command follows the calling sequence of its
corresponding C function exactly; the number and order of
arguments can be determined by looking at the standard docu-
mentation for the function. Example:
XtMapWidget $FORM
A category 2 command also generally follows the calling
sequence as its corresponding C function. Where a C caller
would pass in a pointer to a variable in which a value is
returned, the dtksh command returns a value in an environ-
ment variable. Example:
XmGetColors $FORM $BG FOREGROUND TOPSHADOW BOTTOMSHADOW SELECT
echo "Foreground color = " $FOREGROUND
A 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 dtksh command requires an
additional argument, which is always the first argument, and
is the name of an environment variable into which the return
value is placed. Example:
Unix System LaboratoLast change: 1 August 1995 46
dtksh(1) USER COMMANDS dtksh(1)
XmTextGetString TEXT_VALUE $TEXT_WIDGET
echo "The value of the text field is "$TEXT_VALUE
A category 4 command returns a Boolean value that can be
used in a conditional expression, just as with the
corresponding C function. If the C function also returns
values through reference variables (as in category 2), the
dtksh command also uses variable names for the corresponding
arguments. Example:
if XmIsTraversable $PUSH_BUTTON; then
echo "The pushbutton is traversable"
else
echo "The pushbutton is not traversable"
fi
Generally, the order and type of arguments passed to a com-
mand matches those passed to the corresponding C function,
except as noted for category 3 commands. Other exceptions
are described in the applicable command descriptions.
Widget Handles
Where a C function returns a widget handle, the correspond-
ing dtksh commands set an environment variable equal to the
widget handle. These are category 3 commands; they take as
one of their arguments the name of an environment variable
in which to return the widget handle. (This is an ASCII
string used by dtksh to access the actual widget pointer.)
For example, either of the following commands could be used
to create a new form widget; in both cases, the widget han-
dle for the new form widget is returned in the environment
variable FORM:
XtCreateManagedWidget FORM name XmForm $PARENT
XmCreateForm FORM $PARENT name
After either of the above commands, $FORM can be used to
reference the form widget. For instance, to create a label
widget within the form widget just created, the following
command could be used:
XmCreateLabel LABEL $FORM namelabelString:"Hi Mom" \
topAttachment:ATTACH_FORM leftAttachment:ATTACH_FORM
There is a special widget handle called NULL, provided for
cases where a shell script may need to specify a NULL
widget. For example, the following disables the defaultBut-
ton resource for a form widget:
XtSetValues $FORM defaultButton:NULL
Unix System LaboratoLast change: 1 August 1995 47
dtksh(1) USER COMMANDS dtksh(1)
Widget Resources
Some of the Xt and Motif commands allow the shell script to
pass in a variable number of arguments, representing
resource and value pairs. This is similar to the arglist
passed in to the corresponding Xt or Motif C function.
Examples of these commands include any of the commands used
to create a widget, and the XtSetValues command. In dtksh,
resources are specified by a string with the following syn-
tax: resource:value.
The name of the resource is given in the resource portion of
the string; it is constructed by taking the corresponding Xt
or Motif resource name and omitting the Xt or Xm prefix.
The value to be assigned to the resource is given in the
value portion of the string. The dtksh utility automati-
cally converts the value string to an appropriate internal
representation. For example:
XtSetValues $WIDGET height:100 width:200 resizePolicy:RESIZE_ANY
XmCreateLabel LABEL $PARENT myLabel labelString:"Close Dialog"
When widget resources are retrieved using XtGetValues, the
return value has the same syntax. For example:
XtGetValues $WIDGET height:HEIGHT resizePolicy:POLICY \
sensitive:SENSITIVE
echo $HEIGHT
echo $POLICY
echo $SENSITIVE
Certain types of resource values have special representa-
tion. These include string tables and bit masks. For
instance, the XmList widget allows a string table to be
specified both for the items and the selectedItems
resources. In dtksh, a string table is represented as a
comma-separated list of strings, which is compatible with
how Motif handles them from a resource file. When a
resource that returns a string table is queried using
XtGetValues(3X), the resulting value is again a comma-
separated set of strings. A resource that expects a bit
mask value to be passed in, expects the mask to be specified
as a string composed of the various mask values separated by
the ``|'' character. When a resource that returns a bit
mask is queried, the return value also is a string
representing the enabled bits, separated by the ``|'' char-
acter. For example, the following sets the mwmFunctions
resource for the VendorShell widget class:
XtSetValues mwmFunctions MWM_FUNC_ALL|MWM_FUNC_RESIZE
Unsupported Resources
The dtksh utility supports most of the resources provided by
Unix System LaboratoLast change: 1 August 1995 48
dtksh(1) USER COMMANDS dtksh(1)
Motif; however, there are certain resources that dtksh does
not support. The list of unsupported resources follows.
Several of these resources can be specified at widget crea-
tion time by using XtSetValues, but cannot be retrieved
using XtGetValues; these are indicated by the asterisk (*)
following the resource name.
All Widget And Gadget Classes:
Any font list resource (*)
Any pixmap resource (*)
Composite:
insertPosition
children
Core:
accelerators
translations (*)
colormap
XmText:
selectionArray
selectionArrayCount
ApplicationShell:
argv
WMShell:
iconWindow
windowGroup
Shell:
createPopupChildrenProc
XmSelectionBox:
textAccelerators
Manager, Primitive and Gadget Subclasses:
userData
XmFileSelectionBox:
dirSearchProc
fileSearchProc
qualifySearchDataProc
EXIT STATUS
See sh(1).
CONSEQUENCES OF ERRORS
See sh(1).
Unix System LaboratoLast change: 1 August 1995 49
dtksh(1) USER COMMANDS dtksh(1)APPLICATION USAGE
Initializing The Toolkit Environment
Before any of the Xlib, Xt or Motif commands can be invoked,
the shell script must first initialize the Xt toolkit by
invoking the XtInitialize command, which returns an applica-
tion shell widget. XtInitialize, as with all of the com-
mands that return a widget handle, returns the widget handle
in the environment variable named in its first argument.
For example:
XtInitialize TOPLEVEL myShellName Dtksh $0$@
Shell script writers should invoke the XtInitialize command
as one of the first commands within a dtksh shell script.
This allows dtksh to locate its message catalog and the
correct app-defaults file. If a shell error occurs before
XtInitialize has been called, it is possible that unlocal-
ized error messages may be displayed. The dtksh utility
provides a default app-defaults file to use if the call to
XtInitialize specifies an application class name of Dtksh.
This app-defaults file loads in the standard set of desktop
application default values, so that these applications have
a consistent look with other desktop applications.
Responding to a Window Manager Close Notice
When the user selects the Close item on the window manager
menu for an application, the application is terminated
unless it has arranged to catch the Close notification.
Multiple windows managed by the application disappear, and
application data may be left in an undesirable state. To
avoid this, dtksh provides for catching and handling the
Close notification. The application must:
o Define a procedure to handle the Close notification
o Request notification when Close is selected and over-
ride the response, so the application is not shut down
The following code illustrates this processing:
# This is the `callback' invoked when the user selects
# the `Close' menu item
WMCallback()
{
echo "User has selected the Close menu item"
}
# Create the toplevel application shell
XtInitialize TOPLEVEL test Dtksh "$@"
XtDisplay DISPLAY $TOPLEVEL
# Request notification when the user selects the `Close'
# menu item
Unix System LaboratoLast change: 1 August 1995 50
dtksh(1) USER COMMANDS dtksh(1)
XmInternAtom DELETE_ATOM $DISPLAY "WM_DELETE_WINDOW" false
XmAddWMProtocolCallback $TOPLEVEL $DELETE_ATOM "WMCallback"
# Ask Motif to not automatically close down your
# application window
XtSetValues $TOPLEVEL deleteResponse:DO_NOTHING
Responding to a Session Management Save State Notice
Session management facilities allow applications to save
their current state when the user terminates the current
session, so that when the user later restarts the session,
an application returns to the state it was in. In dtksh
this is accomplished by setting up a handler analogously to
handling a Close notification. If no such handler is set
up, the application has to be restarted manually in the new
session, and does not retain any state. To set up a handler
to save state, the application must do the following:
o Define functions to save state at end-of-session, and
restore it on start-up.
o Register interest in the session management notifica-
tion.
o Register the function to save state.
o Determine if saved state should be restored at start-
up.
The following code illustrates this process:
#! /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 "-" $TOPLEVEL)
$(XtWindow "-" $TOPLEVEL)
CURRENT_WS_LIST ;
then
# Map the comma-separated list of atoms into
# their string representation
Unix System LaboratoLast change: 1 August 1995 51
dtksh(1) USER COMMANDS dtksh(1)
oldIFS=$IFS
IFS=","
for item in $CURRENT_WS_LIST;
do
XmGetAtomName NAME $(XtDisplay "-" $TOPLEVEL)
$item
print -u9 $NAME
done
IFS=$oldIFS
fi
exec 9<&-
# Let the session manager know how to invoke us when
# the session is restored
DtSetStartupCommand $TOPLEVEL
"/usr/dt/contrib/dtksh/SessionTest $SAVEFILE"
else
echo "DtSessionSavePath FAILED!!"
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<$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=""
while read -u9 NAME
do
XmInternAtom ATOM $(XtDisplay "-" $TOPLEVEL)
$NAME False
if [ ${#WS_LIST} -gt 0 ]; then
WS_LIST=$WS_LIST,$ATOM
else
WS_LIST=$ATOM
fi
done
DtWsmSetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL)
$(XtWindow "-" $TOPLEVEL) $WS_LIST
Unix System LaboratoLast change: 1 August 1995 52
dtksh(1) USER COMMANDS dtksh(1)
exec 9<&-
else
echo "DtSessionRestorePath FAILED!!"
exit -3
fi
}
################## Create the Main UI #######################
XtInitialize TOPLEVEL wmProtTest Dtksh "$@"
XtCreateManagedWidget DA da XmDrawingArea $TOPLEVEL
XtSetValues $DA height:200 width:200
XmInternAtom SAVE_SESSION_ATOM $(XtDisplay "-" $TOPLEVEL)
"WM_SAVE_YOURSELF" 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 "-" $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 "-" $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
Cooperating with WorkSpace Management
The dtksh utility provides access to all of the major
workspace management functions of the desktop libraries,
including functions for:
o Querying and setting the set of workspaces with which
an application is associated.
o Querying the list of all workspaces.
o Querying and setting the current workspace.
o Requesting that an application be notified any time
the user changes to a different workspace.
Unix System LaboratoLast change: 1 August 1995 53
dtksh(1) USER COMMANDS dtksh(1)
From a user's perspective, workspaces are identified by a
set of names, but from the workspace manager's perspective,
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, 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 Ses-
sion Management shell script example, if the shell script is
going to save and restore workspace identifiers, the
workspace 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 uses the following
two commands:
XmInternAtom ATOM $DISPLAY $WORKSPACE_NAME false
XmGetAtomName NAME $DISPLAY $ATOM
Creating Localized Shell Scripts
Scripts written for dtksh are internationalized, and then
localized, in a process very 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 catalog, 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 (correspond-
ing to the catalog), and a message number within the set;
these values determine what text the user sees. The follow-
ing code illustrates the process:
# Attempt to open our message catalog
catopen MSG_CAT_ID "myCatalog.cat"
# The localized button label is in set 1, and is message # 2
XtCreatePushButton OK $PARENT ok
labelString:$(catgets $MSG_CAT_ID 1 2 "OK")
# The localized button label is in set 1, and is message #3
XtCreatePushButton CANCEL $PARENT cancel
labelString:$(catgets $MSG_CAT_ID 1 3 "Cancel")
# Close the message catalog, when no longer needed
catclose $MSG_CAT_ID
Unix System LaboratoLast change: 1 August 1995 54
dtksh(1) USER COMMANDS dtksh(1)
The file descriptor returned by catopen must be closed using
catclose, and not using the sh exec command.
Using the dtksh Utility to Access X Drawing Functions
The commands of the dtksh utility include standard Xlib
drawing functions to draw lines, points, segments, rectan-
gles, arcs and polygons. In the standard C programming
environment, these functions take a graphics context, or GC
as an argument, in addition to the drawing data. In dtksh
drawing functions, a collection of GC options are specified
in the argument list to the command. By default, the draw-
ing commands create a GC that is used for that specific com-
mand and then discarded. If the script specifies the -gc
option, the name of the 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.
-gc GC
GC is the name of an environment variable that has
not yet been initialized, or which has been left
holding a graphic context by a previous drawing
command. If this option is specified, it must be
the first GC option specified.
-foreground color
Foreground color, which can be either the name of a
color or a pixel number.
-background color
Background color, which can be either the name of a
color or a pixel number.
-font font name
Name of the font to be used.
-line_width number
Line width to be used during drawing.
-function drawing function
Drawing function, which can be any of the follow-
ing: xor, or, clear, and, copy, noop, nor, nand,
set, invert, equiv, andReverse, orReverse or copy-
Inverted.
-line_style style
Line style, which can be any of the following:
LineSolid, LineDoubleDash or LineOnOffDash.
Setting Widget Translations:
The dtksh utility provides mechanisms for augmenting, over-
riding and removing widget translations, much as in the C
Unix System LaboratoLast change: 1 August 1995 55
dtksh(1) USER COMMANDS dtksh(1)
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 pro-
cedure). Translations within dtksh are handled in a similar
fashion, except only a single action procedure is available.
This action procedure, named ksh_eval, interprets any argu-
ments passed to it as dtksh commands, and evaluates them
when the translation is triggered. The following shell
script segment gives an example of how translations can be
used:
BtnDownProcedure()
{
echo "Button Down event occurred in button "$1
}
XtCreateManagedWidget BUTTON1 button1 XmPushButton $PARENT
labelString:"Button 1"
translations:'#augment
<EnterNotify>:ksh_eval("echo Button1 entered")
<Btn1Down>:ksh_eval("BtnDownProcedure 1")'
XtCreateManagedWidget BUTTON2 button2 XmPushButton $PARENT
labelString:"Button 2"
XtOverrideTranslations $BUTTON2
'#override
<Btn1Down>:ksh_eval("BtnDownProcedure 2")'
EXAMPLES
None.
SEE ALSOsh(1).
Unix System LaboratoLast change: 1 August 1995 56
