 |
Index for
Section 1 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dtksh(1)
CDE
NAME
dtksh - shell command language interpreter with access to many X, Xt, Xm
and CDE functions
SYNOPSIS
dtksh [-abCefimnuvx] [-o option] [+abCefmnuvx] [+o option] command_string
[command_name [argument...]]
OPTIONS
See ksh93(1CDE).
OPERANDS
See ksh93(1CDE).
DESCRIPTION
The dtksh utility is a version of the KornShell extended to support:
· Access to many X, Xt and Motif facilities from within a shell script
· Fully localized shell scripts
· Access to the CDE application help system
· Customization of script-based GUI attributes (such as font and colors)
using the CDE customization tool
· Response to session-management "Save state" directives
· Response to window-management Close directives
· Access to most of the CDE Desktop Services Message Set
· Access to many of the CDE Data Typing API functions
· Access to the CDE Action API functions
The dtksh utility uses the ksh93 implementation of the Korn shell
libraries.
EXIT STATUS
See ksh93(1CDE).
RESOURCES
The dtksh interpreter has no relevant resources outside of those that
affect the various widgets that can be instantiated from within a dtksh
script. Refer to the manual page of the relevant widget for information on
the resources that apply to that widget.
STDIN
See ksh93(1CDE).
INPUT FILES
See ksh93(1CDE).
ASYNCHRONOUS EVENTS
Default.
STDOUT
See ksh93(1CDE).
STDERR
See ksh93(1CDE).
OUTPUT FILES
None.
EXTENDED DESCRIPTION
The capabilities described here are extensions to those of the ksh command
language interpreter. See ksh93(1CDE). The following subsections give a
synopsis of each of the built-in commands added by dtksh to ksh. In
general, argument ordering and types are the same as for corresponding C
procedures, 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 Desktop 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 variable, 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
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.
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 nonMaskableFlag 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 specified
dtksh command to read all data. If the -r option is not specified, the
specified dtksh command is invoked only when a full line has been read
(that is, a line terminated 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 descriptor, 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; otherwise, 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 procedure to be automatically unregistered.
XtAugmentTranslations widgetHandletranslations
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.
XtClass variable widgetHandle
The command returns the name of the widget class associated 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
CallbackHasSome.
XtInitialize variable shellName applicationClassName applicationName
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 XtInitialize command. Upon completion, the environment
variable DTKSH_ARGV is set to the argument list as returned by the
XtInitialize command; the DTKSH_TOPLEVEL environment variable is set to the
widget handle of the widget created by XtInitialize, and the DTKSH_APPNAME
environment variable is set to the value of the applicationName argument.
The command returns a value that can be used in a conditional.
XtIsManaged widgetHandle
The command returns a value that can be used in a conditional.
XtIsSubclass widgetHandle widgetClass
The widgetClass operand is the name of a widget class. The command returns
a value that can be used in a conditional.
XtNameToWidget variable referenceWidget name
XtIsRealized widgetHandle
The command returns a value that can be used in a conditional.
XtIsSensitive widgetHandle
The command returns a value that can be used in a conditional.
XtIsShell widgetHandle
The command returns a value that can be used in a conditional.
XtLastTimestampProcessed variable display
XtMainLoo
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
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 callbacks, when a callback is removed, the same dtksh
command string must be specified as was specified when the callback 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 nonMaskableFlag 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 specified 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...]
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 [protocolAtom...]
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 following 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...]
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...]
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...]
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
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 variable3 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 conditional.
XmListAddItem widgetHandle position itemString
The ordering of the arguments to the XmListAddItem command differs from the
corresponding C function.
XmListAddItems widgetHandle position itemString [itemString...]
The ordering of the arguments to the XmListAddItems command differs from
the corresponding C function.
XmListAddItemsUnselected widgetHandle position [itemString] [itemString...]
The ordering of the arguments to the XmListAddItemsUnselected command
differs from the corresponding C function.
XmListAddItemUnselected widgetHandle position itemString
The ordering of the arguments to the XmListAddItemUnselected command
differs from the corresponding C function.
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 conditional.
XmListItemPos variable widgetHandle itemString
XmListPosSelected widgetHandle position
The command returns a value that can be used in a conditional.
XmListPosToBounds widgetHandle position variable variable2 variable3
variable4
The command returns a value that can be used in a conditional.
XmListReplaceItemsPos widgetHandle position itemString [itemString...]
The ordering of the arguments to the XmListReplaceItemsPos command differs
from the corresponding C function.
XmListReplaceItemsPosUnselected widgetHandle position itemString
[itemString...]
The ordering of the arguments to the XmListReplaceItemsPosUnselected
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 conditional.
XmListSetPos widgetHandle position
XmListUpdateSelectedList widgetHandle
XmMainWindowSep1 variable widgetHandle
XmMainWindowSep2 variable widgetHandle
XmMainWindowSep3 variable widgetHandle
XmMainWindowSetAreas widgetHandle menuWidgetHandle commandWidgetHandle
horizontalScrollbarWidgetHandle verticalScrollbarWidgetHandle
workRegionWidgetHandle
XmMenuPosition widgetHandle eventHandle
The eventHandle operand refers to an XEvent that has typically 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 conditional.
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 [protocolAtom...]
The protocolAtom operand is typically obtained using the XmInternAtom
command.
XmScaleGetValue widgetHandle variable
XmScaleSetValue widgetHandle value
XmScrollBarGetValues widgetHandle variable variable2 variable3 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_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.
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 conditional.
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 conditional.
XmTextGetString variable widgetHandle
XmTextGetTopCharacter variable widgetHandle
XmTextInsert widgetHandle position string
XmTextPaste widgetHandle
The command returns a value that can be used in a conditional.
XmTextPosToXY widgetHandle position variable variable2
The command returns a value that can be used in a conditional.
XmTextRemove widgetHandle
The command returns a value that can be used in a conditional.
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
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 conditional.
XmTextFieldGetInsertionPosition variable widgetHandle
XmTextFieldGetLastPosition variable widgetHandle
XmTextFieldGetMaxLength variable widgetHandle
XmTextFieldGetSelection variable widgetHandle
XmTextFieldGetSelectionPosition widgetHandle variable variable2
The command returns a value that can be used in a conditional.
XmTextFieldGetString variable widgetHandle
XmTextFieldInsert widgetHandle position string
XmTextFieldPosToXY widgetHandle position variable variable2
The command returns a value that can be used in a conditional.
XmTextFieldRemove widgetHandle
The command returns a value that can be used in a conditional.
XmTextFieldReplace widgetHandle fromPosition toPosition string
XmTextFieldSetEditable widgetHandle editableFlag
The editableFlag operand can be set to either True or False.
XmTextFieldSetHighlight widgetHandle leftPosition rightPosition 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 lastPosition 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 conditional.
XmTextFieldSetAddMode widgetHandle state
The state operand can be set to either True or False.
XmToggleButtonGadgetGetState widgetHandle
The command returns a value that can be used in a conditional.
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 conditional.
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 CDE 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
variable2 is set to the widgetHandle for the selected widget.
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 variable. If a shell script needs to
close the file descriptor associated with a message catalog, the catalog ID
must be closed using the catclose command.
catgets variable catalogId setNumber messageNumber defaultMessageString
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 message 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 indicated 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 information) 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 conditional.
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 application 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 whenever the user
changes workspaces. The handle associated with this callback is returned in
the environment variable 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, indicating 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.
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 command
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 backdrop 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 databases. 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 notification 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 conditional.
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 specified.
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 supported in CDE 1.0, and should be specified as a
null ("") value.
Built-in Data Typing Commands
DtDtsLoadDataType
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 attribute 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.
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 attribute names defined
for the indicated data type in variable. 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 conditional.
Built-in CDE Desktop Services Message Set Commands
The following set of commands implement a subset of the Desktop Services
Message Set, allowing shell script participation in the Desktop Services
protocol. Many of the ToolTalk commands differ slightly from their
associated C programming call. For ToolTalk commands that typically return
a pointer, a C application can validate that pointer by calling 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 occurring, 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 Tttt_c(5).
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(3) and in the manual pages for
the individual 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
alternative 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 containing 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
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
registering tttk_Xt_input_handler as an alternative Xt input handler, it
must be registered as a raw handler to prevent dtksh from automatically
breaking 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
environment variable.
ttdt_close status procId newProcId sendStopped
This command closes the indicated communications connection, 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 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 message.
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 effective 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).
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 message was not consumed. If the message was consumed, the
callback should return zero, or one of the values returned by the
tt_error_pointer command. 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 command 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 indicated 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 indicated 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 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 statusmsg
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 message. It then 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 command
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 destroy
This command sets the status and the status string for the indicated
request message, and then it fails the message. 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 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 argument. 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 debugging information by including:
· 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.
· The list of resources supported by a particular widget class.
· The list of constraint resources supported by a particular widget
class.
DtWidgetInfo is called by using any of the following syntaxes; 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 environment 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.
DtWidgetInfo -R [widgetHandle | widgetClass]
If no arguments are supplied, the list of supported constraint resources,
if any, 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.
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 CDE system includes a file of dtksh convenience functions. 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 dialogs
(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 convenience 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 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, containing 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 configured 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.
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 convenient 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, DtkshFloatBottom
These convenience functions simplify the specification of certain classes
of form constraints. They provide a convenient 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]
The optional position argument specifies the relative position to which the
indicated edge of the component is positioned. A default position is used,
if one is not specified.
Example:
XtCreateManagedWidgetBUTTON1 button1 pushButton \
$FORM labelString:"Ok" $(DtkshUnder $SEPARATOR) \
$(DtkshFloatLeft 10) $(DtkshFloatRight 40)
DtkshAnchorRight, DtkshAnchorLeft, DtkshAnchorTop, DtkshAnchorBottom
These convenience functions simplify the specification of certain classes
of form constraints. They provide a convenient 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 component, the
component may still grow or shrink in size. This behavior is accomplished
using the ATTACH_FORM constraint.
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 convenient 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
component (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.
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 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_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 application 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 convenience 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 argument 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
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 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 significant.
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 documentation 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 environment 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:
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 command 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 corresponding 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 handle 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 defaultButton resource for a form widget:
XtSetValues $FORM defaultButton:NULL
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 syntax: 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 automatically
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 representation. 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(3Xt), 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 ``|'' character. 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 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 creation 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
CONSEQUENCES OF ERRORS
See ksh93(1CDE).
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 application shell widget. XtInitialize, as with
all of the commands 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 unlocalized 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:
· Define a procedure to handle the Close notification
· Request notification when Close is selected and override 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
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:
· Define functions to save state at end-of-session, and restore it on
start-up.
· Register interest in the session management notification.
· Register the function to save state.
· 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
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
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:
· Querying and setting the set of workspaces with which an application
is associated.
· Querying the list of all workspaces.
· Querying and setting the current workspace.
· Requesting that an application be notified any time the user changes
to a different workspace.
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
Session 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
(corresponding to the catalog), and a message number within the set; these
values determine what text the user sees. The following code illustrates
the process:
# 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
The file descriptor returned by catopen must be closed using catclose, and
not using the ksh 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, rectangles, 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 drawing commands create a GC that is
used for that specific command 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 following: xor, or, clear,
and, copy, noop, nor, nand, set, invert, equiv, andReverse, orReverse
or copyInverted.
-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, overriding and
removing widget translations, much as in the C programming environment. In
C, an application installs a set of translation action procedures, which
can then be attached to specific sequences of events (translations are
composed of an event sequence and the associated action procedure).
Translations within dtksh are handled in a similar fashion, except only a
single action procedure is available. This action procedure, named
ksh_eval, interprets any arguments 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.
ENVIRONMENT VARIABLES
The following information describes the environment variables that dtksh
uses that are in addition to those documented in the manual page for the
ksh command language interpreter.
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 argument to the command (in the synopses
for these special commands, the first argument has the name variable). If
this return value is immediately used in an expression, the special
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. Commands 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_...()
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 determine what
condition led to its call. For a C procedure, this information is typically
passed in a call_data structure. For example, a Scale widget invoking a
valueChangedCallback 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 following 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 usefulness 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 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 callback 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
structures. The exception to this is the XmTextVerifyCallbackStruct,
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.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"
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 environment 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.
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 standard XEvents are accessed using the event
type XANY, followed 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 previously 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(3Xt) 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 continuations.
The dtksh utility also supports the XtAddInput(3Xt) facility, but has
limited its functionality to reading data, and has taken the reading
function a step further to make it easier 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 complete line of text
has been received. A complete line of text is defined to be a line
terminated either by an unescaped 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(3Xt)
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 information. If the input source does contain binary information, 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 environment variables before calling the
shell script's input handler. These environment variables provide the input
handler with everything needed to handle the incoming data:
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 operating 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 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.
SEE ALSO
ksh93(1CDE)
|
Index for
Section 1 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|