# dtksh Commandscommands

This appendix contains a list of the commands supported by `dtksh`. Many of these commands are almost identical to their Motif, Xt Intrinsics, or Xlib counterparts. Commands that return a value must have the return variable as an environment variable that is the first parameter in the call. Some commands have more differences.

The following subsections give a synopsis of each of the `dtksh` commands. In general, parameter ordering and types are the same as for corresponding C procedures; exceptions are noted. For more detail on the functionality and parameters of a command, see the standard documentation for the corresponding Xlib, Xt Intrinsics, or Motif procedure.

In the command definitions, parameters named var, var2, var3, and so on, indicate that the shell script should supply the name of an environment variable into which some value will be returned. The word variable indicates an environment variable that accepts a return value.

Commands that return a Boolean value (which can be used directly as part of an if statement), are noted as such.

Parameters enclosed within `[]` are optional.

## 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` d isplay 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 ...]

where coordinateMode 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 ...]

where coordinateMode 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 ...

where shape is either `Complex`, `Convex,` or `Nonconvex,` and 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

where discard is either `true` or `false.`

`XTextWidth` variable fontName string

The `XTextWidth` command is different from the corresponding Xlib procedure because it takes the name of a font instead of a pointer to a font structure.

`XUndefineCursor` display window

`XWidthOfScreen` variable screen

## Built-in Xt Intrinsic Commands

All the Xt Intrinsics commands used to create a new widget require that you specify a widget class for the new widget. The widget (or gadget) class name is the standard class name provided by Motif. For example, the class name for a Motif push button widget is `XmPushButton`, while the class name for the Motif label gadget is `XmLabelGadget`.

`XtAddCallback` widgetHandle callbackName ksh-command `
`

where callbackName is one of the standard Motif or Xt callback names, with the `Xt` or `Xm` prefix dropped. For example, `activateCallback`.

`XtAddEventHandler` widgetHandle eventMask nonMaskableFlag ksh-command`
`

where eventMask is of the form mask|mask|mask and the mask components are any of the standard set of X event masks, and nonMaskableFlag is either `true` or `false`.

`XtAddInput` variable [-r] fileDescriptor ksh-command`
`

Registers the indicated file descriptor with the X Toolkit as an alternate input source. It is the responsibility of the shell script's input handler to unregister the input source when it is no longer needed and to close the file descriptor.

If the `-r` option is specified (raw mode), then `dtksh` does not automatically read any of the data available from the input source; it will be up to the specified kshell command to read all data. If the `-r` option is not specified, then the command specified in ksh-command is invoked only when a full line is read (that is, a line terminated by either an unescaped newline character or the end of the file) or when the end of the file is reached. The raw mode is useful for handlers that expect to process nontextual data, or for handlers that do not want `dtksh` automatically reading in a line of data. When the end of file is detected, it is the shell script's input handler's responsibility 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, which can be used by the handler. These include:

`INPUT_LINE` | Empty if in raw mode; otherwise, it contains the next line to be processed.
`INPUT_EOF` | Set to true if end-of-file is reached; otherwise, set to false.
`INPUT_SOURCE` | File descriptor associated with this input source.
I`NPUT_ID` | The ID associated with this input handler; returned by `XtAddInput`().

`XtAddTimeout` variable interval ksh-command

`XtAddWorkProc` variable ksh-command

In `dtksh`, the kshell command is typically a kshell function name. Like regular work procedures, this function is expected to return a value that indicates 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 0, then the work procedure remains registered; any other value causes the work procedure to be automatically unregistered.

`XtAugmentTranslations` widgetHandle translations

`XtCreateApplicationShell` variable applicationName widgetClass

[ resource:value ...]

`XtCallCallbacks` widgetHandle callbackName

where callbackName is one of the standard Motif or Xt callback names, with the `Xt` or `Xm` prefix dropped; for example, `activateCallback.`

`XtClass` variable widgetHandle

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:var1 [resource:var2 ...]

`XtHasCallbacks` variable widgetHandle callbackName

where callbackName is one of the standard Motif or Xt callback names, with the `Xt` or `Xm` prefix dropped; for example, `activateCallback.`

variable is set to one of the strings `CallbackNoList`, `CallbackHasNone`, or `CallbackHasSome`.

`XtInitialize` variable shellName applicationClassName applicationName

[arguments]

Using `Dtksh` as the applicationClassName causes the application to use the default `dtksh` `app-defaults` file. The arguments parameter is used to reference any command-line arguments that might have been specified by the user of the shell script; these are typically referred to using the shell syntax of “$@“.

Returns a value which can be used in a conditional statement.

`XtIsManaged` widgetHandle

Returns a value which can be used in a conditional statement.

`XtIsSubclass` widgetHandle widgetClass

where widgetClass is the name of a widget class. Returns a value which can be used in a conditional statement.

`XtNameToWidget` variable referenceWidget name

`XtIsRealized` widgetHandle

Returns a value which can be used in a conditional statement.

`XtIsSensitive` widgetHandle

Returns a value which can be used in a conditional statement.

`XtIsShell` widgetHandle

Returns a value which can be used in a conditional statement.

`XtLastTimestampProcessed` variable display

`XtMainLoop`

`XtManageChild` widgetHandle

`XtManageChildren` widgetHandle[widgetHandle ...]

`XtMapWidget` widgetHandle

`XtOverrideTranslations` widgetHandle translations

`XtParent` variable widgetHandle

`XtPopdown` widgetHandle

`XtPopup` widgetHandle grabType

where grabType is one of the strings `GrabNone`, `GrabNonexclusive` or `GrabExclusive`.

`XtRealizeWidget` widgetHandle

`XtRemoveAllCallbacks` widgetHandle callbackName

where callbackName is one of the standard Motif or Xt callback names, with the `Xt` or `Xm` prefix dropped; for example, `activateCallback`

`XtRemoveCallback` widgetHandle callbackName ksh-command

where callbackName is one of the standard Motif or Xt callback names, with the Xt or Xm prefix dropped; for example, `activateCallback`. As is true with traditional Xt callbacks, when a callback is removed, the same kshell command string must be specified as was specified when the callback was originally registered.

`XtRemoveEventHandler` widgetHandle eventMask nonMaskableFlag ksh-command

where eventMask is of the form mask|mask|mask and the mask components are any of the standard set of X event masks; that is. ButtonPressMask where nonMaskableFlag is either true or false.

As is true with traditional Xt event handlers, when an event handler is removed, the same eventMask, nonMaskableFlag setting, and kshell command string must be specified as was specified when the event handler was originally registered.

`XtRemoveInput` inputId

where inputId is the handle that was returned in the specified environment variable when the alternate input source was registered using the `XtAddInput` command.

`XtRemoveTimeOut` timeoutId

where timeoutId is the handle that was returned in the specified environment variable when the timeout was registered using the `XtAddTimeOut` command.

`XtRemoveWorkProc` workprocID

where workprocID is the handle that was returned in the specified environment variable when the work procedure was registered using the `XtAddWorkProc` command.

`XtScreen` variable widgetHandle

`XtSetSensitive` widgetHandle state

where state 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 ksh-command

where protocolAtom is typically obtained using the `XmInternAtom` command.

`XmAddWMProtocols` widgetHandle protocolAtom [protocolAtom ...]

where protocolAtom is typically obtained using the `XmInternAtom` command.

`XmCommandAppendValue` widgetHandle string

`XmCommandError` widgetHandle errorString

`XmCommandGetChild` variable widgetHandle childType

where `childType` is one of the strings `DIALOG_COMMAND_TEXT`, `DIALOG_PROMPT_LABEL`, `DIALOG_HISTORY_LIST`, or `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

where childType 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`, or `DIALOG_WORK_AREA`.

`XmGetAtomName` variable display atom

`XmGetColors` widgetHandle background variable var2 var3 var4

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

where onlyIfExistsFlag can be set to either true or false.

`XmIsTraversable` widgetHandle

Returns a value which can be used in a conditional statement.

`XmListAddItem` widgetHandle position itemString

The order of the parameters for the `XmListAddItem` command is not identical to its corresponding C programming counterpart.

`XmListAddItems` widgetHandle position itemString [itemString ...]

The order of the parameters for the `XmListAddItems` command is not identical to its corresponding C programming counterpart.

`XmListAddItemsUnselected` widgetHandle position itemString [itemString ...]

The order of the parameters for the `XmListAddItemsUnselected` command is not identical to its corresponding C programming counterpart.

`XmListAddItemUnselected` widgetHandle position itemString

The ordering of the parameters to the `XmListAddItemUnselected` command are not identical to its corresponding C programming counterpart.

`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

Returns a comma-separated list of indices in variable. Returns a value which can be used in a conditional statement.

`XmListGetKbdItemPos` variable widgetHandle

`XmListGetMatchPos` variable widgetHandle itemString

Returns a comma-separated list of indices in variable. Returns a value which can be used in a conditional statement.

`XmListItemExists` widgetHandle itemString

Returns a value which can be used in a conditional statement.

`XmListItemPos` variable widgetHandle itemString

`XmListPosSelected` widgetHandle position

Returns a value which can be used in a conditional statement.

`XmListPosToBounds` widgetHandle position variable var2 var3 vari4

Returns a value which can be used in a conditional statement.

`XmListReplaceItemsPos` widgetHandle position itemString [itemString ...]

The order of the parameters for the `XmListReplaceItemsPos` command is not identical to its corresponding C programming counterpart.

`XmListReplaceItemsPosUnselected` widgetHandle position itemString

[itemString ...]

The order of the parameters for the `XmListReplaceItemsPosUnselected` command is not identical to its corresponding C programming counterpart.

`XmListSelectItem` widgetHandle itemString notifyFlag

where notifyFlag can be set to either true or false.

`XmListSelectPos` widgetHandle position notifyFlag

where notifyFlag can be set to either true or false.

`XmListSetAddMode` widgetHandle state

where state can be set to either true or false.

`XmListSetBottomItem` widgetHandle itemString

`XmListSetBottomPos` widgetHandle position

`XmListSetHorizPos` widgetHandle position

`XmListSetItem` widgetHandle itemString

`XmListSetKbdItemPos` widgetHandle position

Returns a value which can be used in a conditional statement.

`XmListSetPos` widgetHandle position

`XmListUpdateSelectedList` widgetHandle

`XmMainWindowSep1` variable widgetHandle

`XmMainWindowSep2` variable widgetHandle

`XmMainWindowSep3` variable widgetHandle

`XmMainWindowSetAreas` widgetHandle menuWidgetHandle

commandWidgetHandle

horizontalScrollbarWidgetHandle

verticalScrollbarWidgetHandle

workRegionWidgetHandle

`XmMenuPosition` widgetHandle eventHandle

where eventHandle refers to an X event, which has typically been obtained by accessing the `CB_CALL_DATA.EVENT, EH_EVENT` or `TRANSLATION_EVENT` environment variables.

`XmMessageBoxGetChild` variable widgetHandle childType

where childType is one of the strings `DIALOG_CANCEL_BUTTON, DIALOG_DEFAULT_BUTTON, DIALOG_HELP_BUTTON, DIALOG_MESSAGE_LABEL, DIALOG_OK_BUTTON, DIALOG_SEPARATOR,` or `DIALOG_SYMBOL_LABEL`.

`XmOptionButtonGadget` variable widgetHandle

`XmOptionLabelGadget` variable widgetHandle

`XmProcessTraversal` widgetHandle direction

where direction 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`, or `TRAVERSE_UP`.

Returns a value which can be used in a conditional statement.

`XmRemoveWMProtocolCallback` widgetHandle protocolAtom ksh-command

where protocolAtom is typically obtained using the `XmInternAtom` command.

As is true with traditional Window Manager callbacks, when a callback is removed, the same kshell command string must be specified, as was specified when the callback was originally registered.

`XmRemoveWMProtocols` widgetHandle protocolAtom [ protocolAtom ...]

where protocolAtom is typically obtained using the `XmInternAtom` command.

`XmScaleGetValue` widgetHandle variable

`XmScaleSetValue` widgetHandle value

`XmScrollBarGetValues` widgetHandle variable var2 var3 var4

`XmScrollBarSetValues` widgetHandle value sliderSize increment pageIncrement notifyFlag

where notifyFlag can be set to either true or false.

`XmScrollVisible` widgetHandle widgetHandle leftRightMargin topBottomMargin

`XmSelectionBoxGetChild` variable widgetHandle childType

where childType 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`, or `DIALOG_WORK_AREA`.

`XmTextClearSelection` widgetHandle time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

`XmTextCopy` widgetHandle time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

Returns a value which can be used in a conditional statement.

`XmTextCut` widgetHandle time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

Returns a value which can be used in a conditional statement.

`XmTextDisableRedisplay` widgetHandle

`XmTextEnableDisplay` widgetHandle

`XmTextFindString` widgetHandle startPosition string direction variable

where direction is one of the strings `TEXT_FORWARD` or `TEXT_BACKWARD`.

Returns a value which can be used in a conditional statement.

`XmTextGetBaseline` variable widgetHandle

`XmTextGetEditable` widgetHandle

Returns a value which can be used in a conditional statement.

`XmTextGetInsertionPosition` variable widgetHandle

`XmTextGetLastPosition` variable widgetHandle

`XmTextGetMaxLength` variable widgetHandle

`XmTextGetSelection` variable widgetHandle

`XmTextGetSelectionPosition` widgetHandle variable var2

Returns a value which can be used in a conditional statement.

`XmTextGetString` variable widgetHandle

`XmTextGetTopCharacter` variable widgetHandle

`XmTextInsert` widgetHandle position string

`XmTextPaste` widgetHandle

Returns a value which can be used in a conditional statement.

`XmTextPosToXY` widgetHandle position variable var2

Returns a value which can be used in a conditional statement.

`XmTextRemove` widgetHandle

Returns a value which can be used in a conditional statement.

`XmTextReplace` widgetHandle fromPosition toPosition string

`XmTextScroll` widgetHandle lines

`XmTextSetAddMode` widgetHandle state

where state can be set to either true or false.

`XmTextSetEditable` widgetHandle editableFlag

where editableFlag can be set to either true or false.

`XmTextSetHighlight` widgetHandle leftPosition rightPosition mode

where mode is one of the strings `HIGHLIGHT_NORMAL`, `HIGHLIGHT_SELECTED` or `HIGHLIGHT_SECONDARY_SELECTED`.

`XmTextSetInsertionPosition` widgetHandle position

`XmTextSetMaxLength` widgetHandle maxLength

`XmTextSetSelection` widgetHandle firstPosition lastPosition time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

`XmTextSetString` widgetHandle string

`XmTextSetTopCharacter` widgetHandle topCharacterPosition

`XmTextShowPosition` widgetHandle position

`XmTextXYToPos` variable widgetHandle x y

`XmTextFieldClearSelection` widgetHandle time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

`XmTextFieldGetBaseline` variable widgetHandle

`XmTextFieldGetEditable` widgetHandle

Returns a value which can be used in a conditional statement.

`XmTextFieldGetInsertionPosition` variable widgetHandle

`XmTextFieldGetLastPosition` variable widgetHandle

`XmTextFieldGetMaxLength` variable widgetHandle

`XmTextFieldGetSelection` variable widgetHandle

`XmTextFieldGetSelectionPosition` widgetHandle variable var2

Returns a value which can be used in a conditional statement.

`XmTextFieldGetString` variable widgetHandle

`XmTextFieldInsert` widgetHandle position string

`XmTextFieldPosToXY` widgetHandle position variable var2

Returns a value which can be used in a conditional statement.

`XmTextFieldRemove` widgetHandle

Returns a value which can be used in a conditional statement.

`XmTextFieldReplace` widgetHandle fromPosition toPosition string

`XmTextFieldSetEditable` widgetHandle editableFlag

where editableFlag can be set to either true or false.

`XmTextFieldSetHighlight` widgetHandle leftPosition rightPosition mode

where mode is one of the strings `HIGHLIGHT_NORMAL`, `HIGHLIGHT_SELECTED`, or `HIGHLIGHT_SECONDARY_SELECTED`.

`XmTextFieldSetInsertionPosition` widgetHandle position

`XmTextFieldSetMaxLength` widgetHandle maxLength

`XmTextFieldSetSelection` widgetHandle firstPosition lastPosition time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

`XmTextFieldSetString` widgetHandle string

`XmTextFieldShowPosition` widgetHandle position

`XmTextFieldXYToPos` variable widgetHandle x y

`XmTextFieldCopy` widgetHandle time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

Returns a value which can be used in a conditional statement.

`XmTextFieldCut` widgetHandle time

where time is typically either obtained from within an X Event or is queried by a call to the `XtLastTimestampProcessed` command.

Returns a value which can be used in a conditional statement.

`XmTextFieldPaste` widgetHandle

Returns a value which can be used in a conditional statement.

`XmTextFieldSetAddMode` widgetHandle state

where state can be set to either true or false.

`XmToggleButtonGadgetGetState` widgetHandle

Returns a value which can be used in a conditional statement.

`XmToggleButtonGadgetSetState` widgetHandle state notifyFlag

where state can be set to either true or false, and where notifyFlag can be set to either true or false.

`XmToggleButtonGetState` widgetHandle

Returns a value which can be used in a conditional statement.

`XmToggleButtonSetState` widgetHandle state notifyFlag

where state can be set to either true or false, and where notifyFlag can be set to either true or false.

`XmUpdateDisplay` widgetHandle

## Built-in Common Desktop Environment Application Help Commands

`DtCreateQuickHelpDialog` variable parentWidgetHandle name

[resource:value ...]

`DtCreateHelpDialog` variable parentWidgetHandle name [resource:value ...]

`DtHelpQuickDialogGetChild` variable widgetHandle childType

where childType is one of the strings `HELP_QUICK_OK_BUTTON, HELP_QUICK_PRINT_BUTTON, HELP_QUICK_HELP_BUTTON, HELP_QUICK_SEPARATOR, HELP_QUICK_MORE_BUTTON`, or `HELP_QUICK_BACK_BUTTON`.

`DtHelpReturnSelectedWidgetId` variable widgetHandle var2

variable is set to one of the strings `HELP_SELECT_VALID, HELP_SELECT_INVALID, HELP_SELECT_ABORT`, or `HELP_SELECT_ERROR`. var2 is set to the widgetHandle for the selected widget.

`DtHelpSetCatalogName` catalogName

## Built-in Common Desktop Environment Print Setup Commands

`DtCreatePrintSetupBox` variable parent name [resource:value...]

Create a print setup box.

`DtCreatePrintSetupDialog` variable parent name [resource:value...]

Create a print setup dialog.

## 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, then 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 parameter. If the message string cannot be located, then 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 libDt Session Management Commands

`DtSessionRestorePath` widgetHandle variable sessionFile

Given the file name for the session file (excluding any path information), this command returns the full path for the session file in the environment variable variable.

Returns 0 if successful, 1 if unsuccessful.

`DtSessionSavePath` widgetHandle variable var2

The full path name for the session file is returned in the environment variable variable. The file name portion of the session file (excluding any path information) is returned in the environment variable indicated by var2.

Returns 0 if successful, 1 if unsuccessful.

`DtShellIsIconified` widgetHandle

Allows a shell script to query the iconified state of a shell window. Returns 0 if successful, 1 if unsuccessful.

`DtSetStartupCommand` widgetHandle commandString

Part of the session management process is telling the Session Manager how to restart your application the next time the user reopens the session. This command passes the specified command string to the Session Manager. The widget handle should refer to an application shell.

`DtSetIconifyHint` widgetHandle iconifyHint

where iconifyHint can be set to either true or false.

Allows the initial iconified state for a shell window to be set. This command only works if the window associated with the widget has been realized but not yet displayed.

## Built-in libDt Workspace Management Commands

`DtWsmAddCurrentWorkspaceCallback` variable widgetHandle ksh-command

Evaluates the specified kshell 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` callbackHandle

Removes a workspace notification callback. When removing a workspace callback, you must pass in the callback handle that was returned when you registered the callback with `DtWsmAddCurrentWorkspaceCallback`.

`DtWsmGetCurrentWorkspace` display rootWindow variable

Returns the X atom that represents the user's current workspace in the environment variable indicated by variable. Use the `XmGetAtomName` command to map the X atom into its string representation.

`DtWsmSetCurrentWorkspace` widgetHandle workspaceNameAtom

Changes the user's current workspace to the workspace indicated by workspaceNameAtom.

Returns 0 if successful, 1 if unsuccessful.

`DtWsmGetWorkspaceList` display rootWindow variable

Returns a string of comma-separated X atoms, representing the current set of workspaces defined for the user, in the environment variable indicated by variable.

Returns 0 if successful, 1 if unsuccessful.

`DtWsmGetWorkspacesOccupied` display window variable

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.

Returns 0 if successful, 1 if unsuccessful.

`DtWsmSetWorkspacesOccupied` display window workspaceList

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

Forces the Window Manager menu to include the functions used to move the window to other workspaces. This command only works if the window is in the withdrawn state.

`DtWsmRemoveWorkspaceFunctions` display window

Forces the Window Manager menu to not display the functions used to move the window to other workspaces; this prevents the window from being moved to any other workspaces. This command only works if the window is in the withdrawn state.

`DtWsmOccupyAllWorkspaces` display window

Requests that a window occupy all workspaces, including new workspaces, as they are created.

`DtWsmGetCurrentBackdropWindows` display rootWindow variable

Returns a string of comma-separated window IDs, representing the set of root backdrop windows.

## Built-in libDt Action Commands

The set of commands in this section provide you with the tools for loading the action databases, querying information about actions defined in the databases, and requesting that an action be initiated.

`DtDbLoad`

Reads in the action and data-types databases. If called multiple times, then the old databases are freed before the new ones are read. This command must be called before any of the other `libDt` action commands, or any of the `libDt` 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` ksh-command

Requests notification whenever the action or data-types databases need to be reloaded. The specified kshell command is executed when the notification is received. Typically, the kshell command includes a call to the `DtDbLoad` command.

`DtActionExists` actionName

Tests to see if an action exists in the database with the name specified by the actionName parameter. Returns a value which can be used in a conditional statement.

`DtActionLabel` variable actionName

Returns the localizable LABEL attribute associated with the indicated action. If the action does not exist, then an empty string is returned.

`DtActionDescription` variable actionName

Returns the value of the DESCRIPTION attribute associated with the indicated action. An empty string is returned if the action is not defined, or if the DESCRIPTION attribute was not specified.

## Built-in libDt Data-Typing Commands

`DtLoadDataTypes`

Loads the data-typing databases and should be invoked before any of the other data-typing commands.

`DtDtsFileToDataType` variable filePath

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

Returns the string representing the value of the specified attribute for the data type associated with the indicated file. If the attribute is not defined, or if the file could not be typed, then the variable argument is set to an empty string.

`DtDtsFileToAttributeList` variable filePath

Returns the space-separated list of attribute names defined for the data type associated with the indicated file. A shell script can then query 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 its corresponding C programming counterpart, in that it only returns the names of the defined attributes and not their values.

`DtDtsDataTypeToAttributeValue` variable dataType attrName optName

Returns the string representing the value of the specified attribute for the indicated data type. If the attribute is not defined, or if the indicated data type does not exist, then the variable argument is set to an empty string.

`DtDtsDataTypeToAttributeList` variable dataType optName

Returns the space-separated list of attribute names defined for the indicated data type. A shell script can then query 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 its corresponding C programming counterpart, in that it only returns the names of the defined attributes and not their values.

`DtDtsFindAttribute` variable name value

Returns a space-separated list of datatype 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

Returns a space-separated list representing all the data types currently defined in the data-types database. If an error occurs, then the variable argument is set to an empty string.

`DtDtsSetDataType` variable filePath dataType override

Sets a data type for the specified directory. The variable argument is set to the resultant saved data type for the directory.

`DtDtsDataTypeIsAction` dataType

Determines whether a particular data type represents an action entry. Returns a value which can be used in a conditional statement.

## Miscellaneous Built-in libDt Commands

`DtGetHourGlassCursor` variable display

Returns the X cursor ID associated with the standard `Dt` hourglass cursor.

`DtTurnOnHourGlass` widgetHandle

Turns on the standard `Dt` hourglass cursor for the indicated widget.

`DtTurnOffHourGlass` widgetHandle

Turns off the standard `Dt` hourglass cursor for the indicated widget.

## Built-in Desktop Services Message Set Commands

The following set of commands implements the minimum subset of the Desktop Services Message Set required to allow a shell script to participate 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 validates that pointer by calling the `tt_ptr_error`() function; this function call returns a `Tt_status` value, which indicates whether the pointer was valid, and if not, why it was not valid. Because of the kshell code's design, the string pointer that the shell script sees is not typically the same as the string pointer returned by the underlying C code. Typically, during shell programming, this is not a problem because the important information is the string value, not the string pointer.

To allow shell scripts to get the status of a pointer, any of the commands that normally 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 following values:

`TT_OK`

`TT_WRN_NOTFOUND`

`TT_WRN_STALE_OBJID`

`TT_WRN_STOPPED`

`TT_WRN_SAME_OBJID`

`TT_WRN_START_MESSAGE`

`TT_ERR_CLASS`

`TT_ERR_DBAVAIL`

`TT_ERR_DBEXIST`

`TT_ERR_FILE`

`TT_ERR_INVALID`

`TT_ERR_MODE`

`TT_ERR_ACCESS`

`TT_ERR_NOMP`

`TT_ERR_NOTHANDLER`

`TT_ERR_NUM`

`TT_ERR_OBJID`

`TT_ERR_OP`

`TT_ERR_OTYPE`

`TT_ERR_ADDRESS`

`TT_ERR_PATH`

`TT_ERR_POINTER`

`TT_ERR_PROCID`

`TT_ERR_PROPLEN`

`TT_ERR_PROPNAME`

`TT_ERR_PTYPE`

`TT_ERR_DISPOSITION`

`TT_ERR_SCOPE`

`TT_ERR_SESSION`

`TT_ERR_VTYPE`

`TT_ERR_NO_VALUE`

`TT_ERR_INTERNAL`

`TT_ERR_READONLY`

`TT_ERR_NO_MATCH`

`TT_ERR_UNIMP`

`TT_ERR_OVERFLOW`

`TT_ERR_PTPE_START`

`TT_ERR_CATEGORY`

`TT_ERR_DBUPDATE`

`TT_ERR_DBFULL`

`TT_ERR_DBCONSIST`

`TT_ERR_STATE`

`TT_ERR_NOMEM`

`TT_ERR_SLOTNAME`

`TT_ERR_XDR`

`TT_DESKTOP_EPERM`

`TT_DESKTOP_ENOENT`

`TT_DESKTOP_EINTR`

`TT_DESKTOP_EIO`

`TT_DESKTOP_EAGAIN`

`TT_DESKTOP_ENOMEM`

`TT_DESKTOP_EACCES`

`TT_DESKTOP_EFAULT`

`TT_DESKTOP_EEXIST`

`TT_DESKTOP_ENODEV`

`TT_DESKTOP_ENOTDIR`

`TT_DESKTOP_EISDIR`

`TT_DESKTOP_EINVAL`

`TT_DESKTOP_ENFILE`

`TT_DESKTOP_EMFILE`

`TT_DESKTOP_ETXBSY`

`TT_DESKTOP_EFBIG`

`TT_DESKTOP_ENOSPC`

`TT_DESKTOP_EROFS`

`TT_DESKTOP_EMLINK`

`TT_DESKTOP_EPIPE`

`TT_DESKTOP_ENOMSG`

`TT_DESKTOP_EDEADLK`

`TT_DESKTOP_ECANCELED`

`TT_DESKTOP_ENOTSUP`

`TT_DESKTOP_ENODATA`

`TT_DESKTOP_EPROTO`

`TT_DESKTOP_ENOTEMPTY`

`TT_DESKTOP_ETIMEDOUT`

`TT_DESKTOP_EALREADY`

`TT_DESKTOP_UNMODIFIED`

`TT_MEDIA_ERR_SIZE`

`TT_MEDIA_ERR_FORMAT`

Some of the commands take a message scope as a parameter. The scope indicates which clients have the potential of receiving the outgoing message. For these commands, the scope parameter can be set to any of the following values:

`TT_SCOPE_NONE`

`TT_SESSION`

`TT_FILE`

`TT_BOTH`

`TT_FILE_IN_SESSION`

`tt_file_netfile` variable status filename

Converts the indicated filename, assumed to be a valid file name on the local host, to its corresponding netfilename format. A netfilename can be passed to other hosts on a network and then converted back to a path relative to the other host, using the `tt_netfile_file` command.

`tt_netfile_file` variable status netfilename

Converts the indicated netfilename to a path name that is valid on the local host.

`tt_host_file_netfile` variable status host filename

Converts the indicated file, assumed to be resident on the specified host, into its corresponding netfilename format.

`tt_host_netfile_file` variable status host netfilename

Converts the indicated netfilename into a valid path on the indicated host.

`ttdt_open` variable status var2 toolname vendor version sendStarted

Opens a ToolTalk communications endpoint. It returns in the variable argument the procID associated with this connection. It returns the file descriptor associated with this connection in var2; this file descriptor can be used to register an alternate Xt input handler. The sendStarted argument is a value and if set to true, causes a `Started` message to be automatically sent.

Any procIDs returned by `ttdt_open` contain embedded spaces. To prevent kshell from interpreting the procID as a multiple parameter (versus a single parameter with embedded spaces), you should always enclose any references to the environment variable containing the procID within double quotes, as shown:

    ttdt_close STATUS “$PROC_ID” ““ True

`tttk_Xt_input_handler` procID source id

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 alternate Xt input handlers.

Note that the `\”` (backslash and double quotation mark) characters before and after the reference to the procID environment variable are necessary, because the value contained in the procID environment variable contains embedded spaces and could be misinterpreted unless escaped as shown.

`ttdt_close` status procID newProcId sendStopped

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 is necessary to enclose any references to the procID environment variable within double quotation marks:

    ttdt_close STATUS “$PROC_ID” “$NEW_PROC_ID” False

`ttdt_session_join` variable status s essId shellWidgetHandle join

Joins the session indicated by the sessId argument as a good desktop citizen, by registering patterns and default callbacks for many standard desktop message interfaces. 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 a Boolean and should be set to true or false. This command returns an opaque pattern handle in the variable argument; when no longer needed, this handle can be destroyed using the `ttdt_session_quit` command.

`ttdt_session_quit` status sessId sessPatterns quit

Destroys the message patterns specified by the sessPatterns argument and, if the quit argument is set to true, quits the session indicated by the sessId argument or quits the default session if sessId is empty.

`ttdt_file_join` variable status pathName scope join ksh-command

Registers interest in the deleted, modified, reverted, moved, and saved messages for the indicated file in the indicated scope. An opaque pattern handle is returned in the variable argument. When no longer interested in monitoring messages for the indicated file, this should be destroyed by calling `ttdt_file_quit`.

The requested ksh-command is evaluated anytime one of the messages is received for the indicated file. When this kshell command is evaluated, the following environment variables are defined and provide additional information about the received message:

`DT_TT_MSG` | Contains the opaque handle for the incoming message
`DT_TT_OP` | Contains the string representing the operation to be performed; that is, `TTDT_DELETED, TTDT_MODIFIED, TTDT_REVERTED, TTDT_MOVED` or `TTDT_SAVED`.
`DT_TT_PATHNAME` | Contains 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 (euid) and effective group ID (egid) 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 in the `DT_TT_MSG` environment variable), then it is assumed that the message was not consumed. If the message was consumed, then the callback should return 0, 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

Destroys the message patterns specified by the patterns argument and unregisters interest in the path name that was passed to the ttdt_file_join command, if quit is set to true. The patterns argument should be the value that was returned by the call to the `ttdt_file_join` command.

`ttdt_file_event` status op patterns send

Creates, and optionally sends, a ToolTalk notice announcing an event pertaining to a file. The file is indicated by the path name that was passed to the `ttdt_file_join` command when patterns was created. The op argument indicates what should be announced for the indicated file, and it can be set to `TTDT_MODIFIED`, `TTDT_SAVED`, or `TTDT_REVERTED`. If op is set to `TTDT_MODIFIED`, then this command registers to handle Get_Modified, Save and Revert messages in the scope specified when the patterns were 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, then the indicated message is sent.

`ttdt_Get_Modified` pathName scope timeout

Sends a Get_Modified request in the indicated scope and waits for a reply or for the specified timeout (in milliseconds) to elapse. A Get_Modified request asks other ToolTalk clients if they have any changes pending on pathname that they intend to make persistent. Returns a value which can be used in a conditional statement. 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

Sends a Save request in the indicated scope and waits for a reply or for the indicated timeout (in milliseconds) to elapse. A Save request asks the handling ToolTalk client to save any changes pending for the file specified in the pathName argument. A status of `TT_OK` is returned if an affirmative reply is received before the timeout elapses. Otherwise, one of the standard `Tt_status` error values is returned.

`ttdt_Revert` status pathName scope timeout

Sends a Revert request in the indicated scope and waits for a reply or for the indicated timeout (in milliseconds) to elapse. A Revert request asks the handling ToolTalk client to discard any changes pending for the file specified in the pathName argument. A status of `TT_OK` is returned if an affirmative reply is received before the timeout elapses. Otherwise, one of the standard Tt_status error values 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. tt_error_pointer can be used by the callback to obtain a return pointer for indicating an error condition.

`tt_error_pointer` variable ttStatus

Returns a “magic value,” which is used by ToolTalk to represent an invalid pointer. The magic value returned depends upon the ttStatus value passed- in. Any of the valid `Tt_status` values may be specified.

`tttk_message_destroy` status msg

Destroys any patterns that may have been stored on the message indicated by the msg argument, and then destroys the message.

`tttk_message_reject` status msg msgStatus msgStatusString destroy

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 can consume a message. It is typically safe to destroy the message, using `tttk_message_destroy`, after rejecting the message.

`tttk_message_fail` status msg msgStatus msgStatusString destroy

Sets the status and the status string for the indicated request message, and then fails 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 can consume a message. It is typically safe to destroy the message, using `tttk_message_destroy`, after failing the message.

`tt_message_reply` status msg

Informs the ToolTalk service that the shell script has handled the message and filled in all return values. The ToolTalk service then sends the reply back to the sending process, filling in the state as `TT_HANDLED`. After replying to a message, it is typically safe to destroy the message, using the `tttk_message_destroy` command.