DTKSH(1)

🌸 NAME 🌸

okay so bestie, welcome to dtksh — from the (user cmd) corner of the manual — which is literally a shell command language interpreter that also happens to have access to a whole bunch of X, Xt, Xm and XCDE functions. like, it's a Korn shell but with main character energy 💅

---

✨ SYNOPSIS ✨

three whole ways to summon it, and yes you need all three:

dtksh [-abCefimnuvx]  [-o option]  [+abCefmnuvx]  [+o option]
[command_file  [argument  | ... ] ]

dtksh [-abCefimnuvx]  [-o option]  [+abCefmnuvx]  [+o option]
[command_string]  [command_name  [argument  | ... ] ]

dtksh [-s]  [-abCefimnuvx]  [-o option]  [+abeCefmnuvx]  [+o  option]
[argument  | ... ]

(no cap, that third one really does say +abeCefmnuvx — iykyk 🫶)

---

🦋 DESCRIPTION 🦋

The dtksh utility is a version of the KornShell that's been extended to support all of this:

• Access to many X, Xt and Motif facilities from within a shell script
• Fully localized shell scripts
• Access to the XCDE application help system
• Customization of script-based GUI attributes (such as font and colors) using the XCDE customization tool
• Response to session-management Save state directives
• Response to window-management Close directives
• Access to most of the XCDE Desktop Services Message Set
• Access to many of the XCDE Data Typing API functions
• Access to the XCDE Action API functions

like... she's a shell but she also does GUI things. obsessed. 🎀

---

💜 OPTIONS 💜

See ksh-cde(1).

(that's it. that's the section. she's lowkey mysterious about it ✨)

---

🌸 OPERANDS 🌸

See ksh-cde(1).

(same vibe. go read the other page bestie 😭)

---

🧚 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. So basically: if you wanna know about the resources that apply to a widget, go read that widget's own manual page. she's not doing your homework for you 💅

---

🌈 STDIN 🌈

See ksh-cde(1).

---

🍓 INPUT FILES 🍓

See ksh-cde(1).

---

👑 ENVIRONMENT VARIABLES 👑

okay here's the meaty part, stay with me 🫶 What follows describes the environment variables that dtksh uses in addition to those documented in the manual page for the ksh-cde 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 that's specified as the first argument to the command. (In the synopses for these special commands, the first argument has the name variable.)

So here's the slay part: if that return value gets used immediately in an expression, you can use the special environment variable `-` in place of a variable name. When dtksh encounters `-` as the name of the environment variable where the return value should go, it returns the result as the value of the command instead. Which means your shell script can embed the command call inside another command call. (This feature works only for commands that return a single value — the value is the first argument and that argument has the name variable.)

For example, this:

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. Iconic. 🎀

This capability is available for all category 3 commands except:

• those that create a widget
• those that return more than a single value
• 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_...()

(note the most, bestie — not all of them 🙈)

🌟 Variables Set By XtInitialize 🌟

The XtInitialize command sets the following variables:

DTKSH_APPNAME DTKSH_ARGV DTKSH_TOPLEVEL

🦋 Callback Context Variables 🦋

So an application registers a callback with a widget to say which condition it's interested in, and what action should happen when that condition occurs. That 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 figure out what condition led to its call. For a C procedure, that info 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;

And 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 get 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. So 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

Same deal for 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 that particular callback structure, using the technique described above 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? The XmTextVerifyCallbackStruct, available during the losingFocusCallback, the modifyVerifyCallback and the motionVerifyCallback for the text widget. The dtksh utility supports modifying certain fields within this structure, to the extent that it's supported by Motif. The following fields within the callback structure can be modified:

CB_CALL_DATA.DOIT
CB_CALL_DATA.STARTPOS
CB_CALL_DATA.ENDPOS
CB_CALL_DATA.TEXT.PTR
CB_CALL_DATA.TEXT.LENGTH
CB_CALL_DATA.TEXT.FORMAT

An example of how these fields can be modified:

CB_CALL_DATA.DOIT="false"
CB_CALL_DATA.TEXT.PTR="*"
CB_CALL_DATA.TEXT.LENGTH=1

🔥 Event Handler Context Variables 🔥

As with callbacks, an application registers event handlers with a widget to specify what action should occur when one of the specified events occurs. And 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 like 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 described above 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 gets 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 like a million different configurations depending 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}

(yes bestie, that second one really has a mismatched brace in the original — i'm not fixing it, that's not my job 💀)

🎀 Input Context Variables 🎀

Xt provides the XtAddInput(3) facility that lets an application 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 you're programming in C, the application provides a handler function that gets invoked when the activity occurs. When reading data from the file descriptor, it's up to the handler to read the data from the input source and handle character escaping and line continuations.

---

okay that's the end of this chunk — but there's so much more coming, don't go anywhere 💖

so like, ✨ input handlers ✨ — the dtksh utility also supports the XtAddInput(3) facility, but it's been limited to reading data only, and it took the reading function a whole step further to make life easier for shell programmers. 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. And a "complete line of text" is defined as a line terminated either by an unescaped <newline> character, or by end-of-file. The input handler also gets called if no data is available and end-of-file is reached — which gives the handler the opportunity to use XtRemoveInput(3) to remove the input source, and to close the file descriptor. 🫶

The advantage of this default behavior? Input handlers don't need to do escape processing or handle line continuations, and that's a slay. 💅 The disadvantage? It assumes all of the input is line-oriented and contains no binary information. 😭 So 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. Then it 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). main character energy: the handler does literally everything.

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 give the handler everything it needs to handle the incoming data:

• INPUT_LINE — in 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. In raw mode, this environment variable always contains an empty string. 🫙
• INPUT_EOF — in 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. In raw mode, INPUT_EOF is always set to False.
• INPUT_SOURCE — indicates the file descriptor for which input is available. In raw mode, this file descriptor is used to obtain the pending input. It's also used to close the input source when it's no longer needed.
• INPUT_ID — indicates the ID returned by XtAddInput when the input source was originally registered. You need this to remove the input source using XtRemoveInput. iykyk 🔑

---

✨ ASYNCHRONOUS EVENTS ✨

Default. That's it, that's the whole section, no cap. 😌

---

🌈 STDOUT 🌈

See ksh-cde(1). go look, bestie 🦋

---

🌸 STDERR 🌸

See ksh-cde(1). same deal 💜

---

🎀 OUTPUT FILES 🎀

None. Nothing gets written out. periodt. 🚫

---

👑 EXTENDED DESCRIPTION 👑

Everything described here? Extensions to the capabilities of the ksh-cde command language interpreter. See ksh-cde(1). The following subsections give a synopsis of each of the built-in commands added by dtksh to ksh-cde. In general, argument ordering and types are the same as for the 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 the 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. so you're passing a name, not a value — the value comes back to you through it. 💫

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] — the bell one. ring ring, bestie 🔔
• 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. don't come for me, that's just how it is 💅
• 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's 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 -r 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. 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's 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 [widgetHandle translations]
• XtCreateApplicationShell [variable applicationName widgetClass] [resource:value ...]
• XtCallCallbacks [widgetHandle callbackName]
  • the callbackName operand is one of the standard Motif or Xt callback names, with the Xt or Xm prefix omitted; for example, activateCallback.
• 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]

Okay so, this is the exact same energy as basically every Motif-based program ever 🎀 — the arguments argument is where you hand over whatever command-line args the person running your shell script might've typed, and you'll usually spell that with the shell syntax $@. The applicationName argument is in the list too because $@ doesn't include $0 (rude, but that's the deal 💅). Both applicationName and arguments get used to build the argument list that's passed to XtInitialize. Once that's done, the environment variable DTKSH_ARGV gets set to the argument list as returned by XtInitialize, DTKSH_TOPLEVEL gets set to the widget handle of the widget created by XtInitialize, and DTKSH_APPNAME gets set to the value of the applicationName argument. The command returns a value you can use in a conditional. 🫶

• XtIsManaged [widgetHandle] — returns a value you can drop straight into a conditional ✨
• XtIsSubclass [widgetHandle widgetClass] — the widgetClass operand is the name of a widget class (name, not handle, bestie — read it twice 👀). The command returns a value that can be used in a conditional.
• XtNameToWidget [variable referenceWidget name] — no extra deets in the source, just the signature, so here's the signature 🦋
• XtIsRealized [widgetHandle] — returns a value that can be used in a conditional 💅
• XtIsSensitive [widgetHandle] — returns a value that can be used in a conditional 💅
• XtIsShell [widgetHandle] — returns a value that can be used in a conditional 💅
• XtLastTimestampProcessed [variable display] — signature as shown, no notes 🎀
• XtMainLoop — the whole signature is literally just this. iconic ✨
• XtManageChild [widgetHandle] — yep, that's the whole thing 🌸
• XtManageChildren [widgetHandle] [widgetHandle ...] — one handle, or a whole squad of handles 💖
• XtMapWidget [widgetHandle] — signature exactly as shown 🦋
• XtOverrideTranslations [widgetHandle translations] — takes your widget handle plus the translations, periodt 💅
• XtParent [variable widgetHandle] — no extra description in the original, just the synopsis 🫶
• XtPopdown [widgetHandle] — that's it, that's the signature 🎀
• XtPopup [widgetHandle grabType] — and the grabType operand is one of the strings GrabNone, GrabNonexclusive or GrabExclusive. Three options, no cap 👑
• XtRealizeWidget [widgetHandle] — signature as shown ✨
• 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. (So you strip the prefix — that's the whole vibe check 🔥)
• 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. And 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. Like, the literal same string. No ✨creative✨ rewording. 😭
• 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. And 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. Match all three or it's not coming off, bestie 💀
• 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] — signature as shown, no extras 🌈
• XtSetSensitive [widgetHandle state] — the state operand is either True or False. Binary queen ⭐
• XtSetValues [widgetHandle resource:value] [resource:value ...] — one resource:value pair, or as many as your heart desires 💜
• XtUninstallTranslations [widgetHandle] — that's the whole signature 🎀
• XtUnmanageChild [widgetHandle] — yep 🦋
• XtUnmanageChildren [widgetHandle] [widgetHandle ...] — plural version, many handles welcome 💖
• XtUnmapWidget [widgetHandle] — signature as shown ✨
• XtUnrealizeWidget [widgetHandle] — signature as shown 🌸
• XtWindow [variable widgetHandle] — no extra deets, just the synopsis 🫶

---

💅 Built-in Motif Commands 💅

The Xt commands' louder, more extra cousin. Same energy, more widgets. Let's go 🎀

• XmAddWMProtocolCallback [widgetHandle protocolAtom dtksh-command] — the protocolAtom operand is typically obtained using the XmInternAtom command. (Typically, not always — don't @ me 👀)
• XmAddWMProtocols [widgetHandle protocolAtom] [protocolAtom ...] — the protocolAtom operand is typically obtained using the XmInternAtom command. One atom or a whole pile of 'em 💅
• XmCommandAppendValue [widgetHandle string] — these two got smushed onto one line in the original, so we're giving each its own moment 😭 (see next bullet)
• XmCommandError [widgetHandle errorString] — the second half of that smushed line, liberated ✨
• XmCommandGetChild [variable widgetHandle childType] — and the childType operand is one of these strings:
  • DIALOG_COMMAND_TEXT
  • DIALOG_PROMPT_LABEL
  • DIALOG_HISTORY_LIST
  • DIALOG_WORK_AREA
• XmCommandSetValue [widgetHandle commandString] — signature exactly as shown 🦋

Now the entire create-a-widget collection. Same shape every time: [variable parentWidgetHandle name] plus any number of [resource:value ...] — and yes, every single one is listed, no skips, no "etc." 💀

• XmCreateArrowButton [variable parentWidgetHandle name] [resource:value ...] — obviously 💅
• XmCreateArrowButtonGadget [variable parentWidgetHandle name] [resource:value ...] — the gadget version, of course ✨
• XmCreateBulletinBoard [variable parentWidgetHandle name] [resource:value ...] — pin it up 🎀
• XmCreateBulletinBoardDialog [variable parentWidgetHandle name] [resource:value ...] — bulletin board, but make it a dialog 🌸
• XmCreateCascadeButton [variable parentWidgetHandle name] [resource:value ...] — cascade energy 🦋
• XmCreateCascadeButtonGadget [variable parentWidgetHandle name] [resource:value ...] — gadget cascade, we ride at dawn 💖
• XmCreateCommand [variable parentWidgetHandle name] [resource:value ...] — command widget, iconic 👑
• XmCreateDialogShell [variable parentWidgetHandle name] [resource:value ...] — the shell that holds your dialog 🐚
• XmCreateDrawingArea [variable parentWidgetHandle name] [resource:value ...] — draw bestie ✏️
• XmCreateDrawnButton [variable parentWidgetHandle name] [resource:value ...] — a button that's drawn, yes really 💅
• XmCreateErrorDialog [variable parentWidgetHandle name] [resource:value ...] — for when it goes wrong 😭
• XmCreateFileSelectionBox [variable parentWidgetHandle name] [resource:value ...] — pick a file, any file 🍓
• XmCreateFileSelectionDialog [variable parentWidgetHandle name] [resource:value ...] — same but dialogy ✨
• XmCreateForm [variable parentWidgetHandle name] [resource:value ...] — layout queen 👑
• XmCreateFormDialog [variable parentWidgetHandle name] [resource:value ...] — form, dialog edition 🎀
• XmCreateFrame [variable parentWidgetHandle name] [resource:value ...] — frame it 🖼️
• XmCreateInformationDialog [variable parentWidgetHandle name] [resource:value ...] — just info, no drama 🌸
• XmCreateLabel [variable parentWidgetHandle name] [resource:value ...] — words go here 🏷️
• XmCreateLabelGadget [variable parentWidgetHandle name] [resource:value ...] — words, gadget edition 🦋
• XmCreateList [variable parentWidgetHandle name] [resource:value ...] — a list, bestie 📋
• XmCreateMainWindow [variable parentWidgetHandle name] [resource:value ...] — main character window, literally 🌟
• XmCreateMenuBar [variable parentWidgetHandle name] [resource:value ...] — the bar of menus 🍫
• XmCreateMenuShell [variable parentWidgetHandle name] [resource:value ...] — shell for menus 🐚
• XmCreateMessageBox [variable parentWidgetHandle name] [resource:value ...] — a box of message 💌
• XmCreateMessageDialog [variable parentWidgetHandle name] [resource:value ...] — message, dialog edition ✨
• XmCreateOptionMenu [variable parentWidgetHandle name] [resource:value ...] — choose your option 💅
• XmCreatePanedWindow [variable parentWidgetHandle name] [resource:value ...] — panes for days 🪟
• XmCreatePopupMenu [variable parentWidgetHandle name] [resource:value ...] — pops up 🎈
• XmCreatePromptDialog [variable parentWidgetHandle name] [resource:value ...] — asks you stuff 🙋‍♀️
• XmCreatePulldownMenu [variable parentWidgetHandle name] [resource:value ...] — pulls down ⬇️
• XmCreatePushButton [variable parentWidgetHandle name] [resource:value ...] — push it, push it 🫸
• XmCreatePushButtonGadget [variable parentWidgetHandle name] [resource:value ...] — push it, gadget style 🦋
• XmCreateQuestionDialog [variable parentWidgetHandle name] [resource:value ...] — ❓ asking the real questions
• XmCreateRadioBox [variable parentWidgetHandle name] [resource:value ...] — one at a time, bestie 📻
• XmCreateRowColumn [variable parentWidgetHandle name] [resource:value ...] — rows and columns, the original grid 🧱
• XmCreateScale [variable parentWidgetHandle name] [resource:value ...] — slide it 🎚️
• XmCreateScrollBar [variable parentWidgetHandle name] [resource:value ...] — scroll scroll scroll 📜
• XmCreateScrolledList [variable parentWidgetHandle name] [resource:value ...] — list with scroll ✨
• XmCreateScrolledText [variable parentWidgetHandle name] [resource:value ...] — text with scroll ✨
• XmCreateScrolledWindow [variable parentWidgetHandle name] [resource:value ...] — window with scroll ✨
• XmCreateSelectionBox [variable parentWidgetHandle name] [resource:value ...] — select something 🎯
• XmCreateSelectionDialog [variable parentWidgetHandle name] [resource:value ...] — select something, dialogy 🎀
• XmCreateSeparator [variable parentWidgetHandle name] [resource:value ...] — the line between 🎏
• XmCreateSeparatorGadget [variable parentWidgetHandle name] [resource:value ...] — the line between, gadget edition 🦋
• XmCreateText [variable parentWidgetHandle name] [resource:value ...] — text text text 📝
• XmCreateTextField [variable parentWidgetHandle name] [resource:value ...] — one field of text 🍓
• XmCreateToggleButton [variable parentWidgetHandle name] [resource:value ...] — on/off era 🔁
• XmCreateToggleButtonGadget [variable parentWidgetHandle name] [resource:value ...] — on/off era, gadget 🦋
• XmCreateWarningDialog [variable parentWidgetHandle name] [resource:value ...] — ⚠️ consider this a heads up
• XmCreateWorkArea [variable parentWidgetHandle name] [resource:value ...] — get to work 🛠️
• XmCreateWorkingDialog [variable parentWidgetHandle name] [resource:value ...] — working on it… ⏳

Phew. Every single one, accounted for. No shortcuts, no "and friends" 💀

• XmFileSelectionDoSearch [widgetHandle directoryMask] — signature exactly as shown 🔍
• XmFileSelectionBoxGetChild [variable widgetHandle childType] — and the childType operand is one of these 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] — that's the signature, no extras 🌈
• XmGetColors [widgetHandle background variable variable2 variable3 variable4] — heads up: the XmGetColors command differs from the C procedure in that it takes a widgetHandle instead of a screen pointer and a colormap. Different vibes, same name 👀
• XmGetFocusWidget [variable widgetHandle] — signature as shown 💅
• XmGetPostedFromWidget [variable widgetHandle] — signature as shown 🦋
• XmGetTabGroup [variable widgetHandle] — signature as shown 🎀
• XmGetTearOffControl [variable widgetHandle] — signature as shown ✨
• XmGetVisibility [variable widgetHandle] — signature as shown 🌸
• 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. Yes, really. Check your order, bestie 😭
• XmListAddItems [widgetHandle position itemString] [itemString ...] — the ordering of the arguments to the XmListAddItems command differs from the corresponding C function either. Same warning, plural 🦋
• XmListAddItemsUnselected [widgetHandle position itemString] [itemString ...] — the ordering of the arguments to the XmListAddItemsUnselected command differs from the corresponding C function. Ordering trauma, the gift that keeps giving 💀
• XmListAddItemUnselected [widgetHandle position itemString] — the ordering of the arguments to the XmListAddItemUnselected command differs from the corresponding C function. Fourth time's the charm ✨
• XmListDeleteAllItems [widgetHandle] — signature as shown, wipe it all 🧹
• XmListDeleteItem [widgetHandle itemString] — signature as shown 🎀
• XmListDeleteItems [widgetHandle itemString] [itemString ...] — delete a whole little squad of items from the list, one itemString at a time ✨
• XmListDeleteItemsPos [widgetHandle itemCount position] — deletes itemCount items starting at position. bye bestie 👋
• XmListDeletePos [widgetHandle position] — one item, one position, gone.
• XmListDeletePositions [widgetHandle position] [position ...] — multiple positions, all deleted, no cap 🫶
• XmListDeselectAllItems [widgetHandle] — the "nvm, deselect everything" of widget commands.
• XmListDeselectItem [widgetHandle itemString] — un-highlight that one item, respectfully.
• XmListDeselectPos [widgetHandle position] — same vibe, but you point at it with a position instead 💅
• 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] — grabs the keyboard item position into variable.
• 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. (Yes queen, a real yes/no.)
• XmListItemPos [variable widgetHandle itemString] — drops the item's position into variable.
• 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. That's four whole output variables, she's thorough.
• XmListReplaceItemsPos [widgetHandle position itemString] [itemString ...] — swaps items out starting at position. ⚠️ Heads up: the ordering of the arguments to the XmListReplaceItemsPos command differs from the corresponding C function. Do not come for me, that's just how it is.
• XmListReplaceItemsPosUnselected [widgetHandle position itemString] [itemString ...] — same deal, but the replaced items don't get selected. ⚠️ And yeah — the ordering of the arguments to the XmListReplaceItemsPosUnselected command differs from the corresponding C function. Copy that.
• XmListSelectItem [widgetHandle itemString notifyFlag] — selects an item. The notifyFlag operand can be set to either True or False. 🦋
• XmListSelectPos [widgetHandle position notifyFlag] — selects by position instead of by string. 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] — park that item right at the bottom.
• XmListSetBottomPos [widgetHandle position] — bottom, but by position.
• XmListSetHorizPos [widgetHandle position] — sets the horizontal scroll position, iconic behaviour honestly.
• XmListSetItem [widgetHandle itemString] — the "this one, right here" command.
• XmListSetKbdItemPos [widgetHandle position] — the command returns a value that can be used in a conditional. 🌸
• XmListSetPos [widgetHandle position] — sets the position. deep, I know.
• XmListUpdateSelectedList [widgetHandle] — refreshes the selected list so it matches reality ✨

---

• XmMainWindowSep1 [variable widgetHandle] — hands you separator 1 in variable.
• XmMainWindowSep2 [variable widgetHandle] — separator 2. she's number two for a reason 💀
• XmMainWindowSep3 [variable widgetHandle] — and separator 3, completing the little trio 🎀
• XmMainWindowSetAreas [widgetHandle menuWidgetHandle commandWidgetHandle horizontalScrollbarWidgetHandle verticalScrollbarWidgetHandle workRegionWidgetHandle] — the big one where you hand over every single area of the main window at once. six handles, no notes, slay 🔥
• XmMenuPosition [widgetHandle eventHandle] — positions the menu. 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. iykyk 🫶

---

• XmMessageBoxGetChild [variable widgetHandle childType] — digs out a specific child of the message box into variable.

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] — grabs the option button gadget into variable.
• XmOptionLabelGadget [variable widgetHandle] — and the option label gadget, matching set 💅
• XmProcessTraversal [widgetHandle direction] — moves the traversal cursor around, in whichever direction you say. The command returns a value that can be used in a conditional.

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

---

• XmRemoveWMProtocolCallback [widgetHandle protocolAtom dtksh-command] — removes a WM protocol callback. The protocolAtom operand is typically obtained using the XmInternAtom command. And listen — 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. Same string, exact, don't get cute with it ⚠️
• XmRemoveWMProtocols [widgetHandle protocolAtom] [protocolAtom ...] — removes one or a whole bunch of WM protocols. The protocolAtom operand is typically obtained using the XmInternAtom command. ✨

---

• XmScaleGetValue [widgetHandle variable] — reads the scale's value into variable.
• XmScaleSetValue [widgetHandle value] — sets it. simple as that 🎀
• XmScrollBarGetValues [widgetHandle variable variable2 variable3 variable4] — four values, four variables, one very thorough scrollbar.
• XmScrollBarSetValues [widgetHandle value sliderSize increment pageIncrement notifyFlag] — sets all the scrollbar things. The notifyFlag operand can be set to either True or False. 💖
• XmScrollVisible [widgetHandle widgetHandle leftRightMargin topBottomMargin] — scrolls until the widget is visible, with margins on both axes. she makes sure you're seen 👑

---

• XmSelectionBoxGetChild [variable widgetHandle childType] — grabs a child of the selection box into variable.

The childType operand is one of the strings:

• DIALOG_CANCEL_BUTTON
• DIALOG_DEFAULT_BUTTON
• DIALOG_HELP_BUTTON
• DIALOG_APPLY_BUTTON
• DIALOG_LIST
• DIALOG_LIST_LABEL
• DIALOG_OK_BUTTON
• DIALOG_SELECTION_LABEL
• DIALOG_SEPARATOR
• DIALOG_TEXT
• DIALOG_WORK_AREA

---

• XmTextClearSelection [widgetHandle time] — clears the selection. The time operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. 🕐
• XmTextCopy [widgetHandle time] — copies. 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] — cuts. 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] — no redisplay for you, bestie 🙈
• XmTextEnableDisplay [widgetHandle] — ok and now you can redisplay again 💅
• XmTextFindString [widgetHandle startPosition string direction variable] — finds a string and drops the result in 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] — baseline goes in variable.
• XmTextGetEditable [widgetHandle] — the command returns a value that can be used in a conditional.
• XmTextGetInsertionPosition [variable widgetHandle] — insertion position → variable.
• XmTextGetLastPosition [variable widgetHandle] — last position → variable. 🌸
• XmTextGetMaxLength [variable widgetHandle] — max length → variable.
• XmTextGetSelection [variable widgetHandle] — the current selection → variable. 🎀
• XmTextGetSelectionPosition [widgetHandle variable variable2] — selection position into two variables. The command returns a value that can be used in a conditional.
• XmTextGetString [variable widgetHandle] — the whole string → variable.
• XmTextGetTopCharacter [variable widgetHandle] — top character → variable.
• XmTextInsert [widgetHandle position string] — insert the string at position. ⭐
• XmTextPaste [widgetHandle] — the command returns a value that can be used in a conditional.
• XmTextPosToXY [widgetHandle position variable variable2] — position in, x and y out. 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] — swap everything between fromPosition and toPosition for string.
• XmTextScroll [widgetHandle lines] — scroll by however many 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] — highlights a range, however you want it. The mode operand is one of the strings:
  • HIGHLIGHT_NORMAL
  • HIGHLIGHT_SELECTED
  • HIGHLIGHT_SECONDARY_SELECTED
• XmTextSetInsertionPosition [widgetHandle position] — puts the insertion cursor at position.
• XmTextSetMaxLength [widgetHandle maxLength] — sets the cap at maxLength.
• XmTextSetSelection [widgetHandle firstPosition lastPosition time] — selects from firstPosition to lastPosition. The time operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. 🕐
• XmTextSetString [widgetHandle string] — sets the whole string at once. go off 👑
• XmTextSetTopCharacter [widgetHandle topCharacterPosition] — sets which character is at the top.
• XmTextShowPosition [widgetHandle position] — makes sure position is actually on screen. 🌈
• XmTextXYToPos [variable widgetHandle x y] — the reverse of XmTextPosToXY: x and y in, position out.

---

• XmTextFieldClearSelection [widgetHandle time] — the text field version of clear-selection. The time operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command.
• XmTextFieldGetBaseline [variable widgetHandle] — baseline → variable.
• XmTextFieldGetEditable [widgetHandle] — the command returns a value that can be used in a conditional. 💖
• XmTextFieldGetInsertionPosition [variable widgetHandle] — insertion position → variable.
• XmTextFieldGetLastPosition [variable widgetHandle] — last position → variable.
• XmTextFieldGetMaxLength [variable widgetHandle] — max length → variable.
• XmTextFieldGetSelection [variable widgetHandle] — selection → variable.
• XmTextFieldGetSelectionPosition [widgetHandle variable variable2] — selection position → two variables. The command returns a value that can be used in a conditional.
• XmTextFieldGetString [variable widgetHandle] — the string → variable. ✨
• XmTextFieldInsert [widgetHandle position string] — shove string in at position.
• XmTextFieldPosToXY [widgetHandle position variable variable2] — position → x and y. 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] — replace that range with 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] — insertion cursor goes to position.
• XmTextFieldSetMaxLength [widgetHandle maxLength] — cap it at maxLength.
• XmTextFieldSetSelection [widgetHandle firstPosition lastPosition time] — selects the range. The time operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. 🕐
• XmTextFieldSetString [widgetHandle string] — set the string, done.
• XmTextFieldShowPosition [widgetHandle position] — scroll her into view.
• XmTextFieldXYToPos [variable widgetHandle x y] — x and y in, position out.
• XmTextFieldCopy [widgetHandle time] — copies from the text field. 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] — cuts from the text field. 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] — forces the display to actually update. queen of follow-through ✨

---

🧚 Built-in XCDE Application Help Commands 🧚

• DtCreateHelpQuickDialog [variable parentWidgetHandle name] [resource:value ...] — spins up a quick help dialog and hands it back in variable, parented to parentWidgetHandle, with a name and then as many resource:value pairs as your heart desires. 💜

okay so we're still deep in the extended-description cinematic universe, and this batch is giving desktop built-ins — help dialogs, sessions, workspaces, actions, data typing, and the XCDE message-set girlies. keep your args exactly as written, bestie. 💅

• DtCreateHelpDialog [variable parentWidgetHandle name] [resource:value ...] — this is the help-dialog creation signature. the source doesn't add extra prose here, so just hold the shape: variable, parentWidgetHandle, name, and then any resource:value pairs.
• DtHelpQuickDialogGetChild [variable widgetHandle childType] — grabs the child you asked for out of a quick help dialog. childType is one of these exact strings, no improv:

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] — returns the selected widget id situation. the variable operand is set to one of these strings:

HELP_SELECT_VALID
HELP_SELECT_INVALID
HELP_SELECT_ABORT
HELP_SELECT_ERROR

and variable2 is set to the widgetHandle for the selected widget. 🫶

• DtHelpSetCatalogName [catalogName] — signature only in the source, so keep it exactly like that.

---

🌸 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. do not skip that part.
• 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. it returns a value you can use in a conditional, indicating whether the command succeeded.
• DtSessionSavePath [widgetHandle variable variable2] — the full pathname for the session file is returned in the 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. short and sweet.
• 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. big caveat: 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] — 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. no random handles, bestie.
• DtWsmGetCurrentWorkspace [display rootWindow variable] — 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] — 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] — 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] — 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] — 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] — signature only in the source, no extra prose. keep the shape.
• DtWsmRemoveWorkspaceFunctions [display window] — same deal, signature only.
• DtWsmOccupyAllWorkspaces [display window] — also signature only.
• DtWsmGetCurrentBackdropWindows [display rootWindow variable] — 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. very "I got the tools" energy.

• DtDbLoad — 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. this is a must-do, not a maybe.
• 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 — here's the exact signature:

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 XCDE 1.0, and should be specified as a null ("") value.

---

💜 Built-in Data Typing Commands 💜

• DtDtsLoadDataTypes — this command should be invoked before any of the other data typing commands. do it first, bestie.
• 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 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] — 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] — 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] — 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] — 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] — 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 XCDE 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 Tt/tt_c.h - Tttt_c(5).

okay so some of these commands take a message scope as an argument. bestie, for those 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] — converts a file name to a netfile name, putting the result in variable and the status in status. ✨
• tt_netfile_file [variable status netfile name] — the reverse, converting a netfile name back to a file name. 🦋
• tt_host_file_netfile [variable status host file name] — like tt_file_netfile but with an explicit host. 🌸
• tt_host_netfile_file [variable status host netfile name] — and the host version of the reverse. 🎀
• 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
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

The 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 command 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 [status msg] — This command destroys any patterns that may have been stored on the message indicated by the msg argument, and then it destroys the message. 💀
• tttk_message_reject [status msg msgStatus msgStatusString destroy] — This command sets the status and the status string for the indicated request message, and then rejects the 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 ]

Okay so — if you pass no arguments at all, the list of supported resources gets written to standard output for all the available widget classes. But if you do hand it arguments, they should be either widget handles or widget class names, and then the info gets written only for the set of widgets or widget classes you actually asked about. Targeted. Iconic. 💅

DtWidgetInfo [-R]  [widgetHandle  | widgetClass ]

Same energy, different flag: with no arguments, the list of supported constraint resources (if there are any, no pressure) is written to standard output for all available widget classes. With arguments, they should be widget handles or widget class names, and the info is written only for the widgets or widget classes you named. Slay. ✨

DtWidgetInfo [-c]  [widgetClass]

No arguments? The list of supported widget class names goes to standard output. Arguments? Then dtksh writes the widget class name — if it's defined — and otherwise it writes an error message to standard error. So like, defined = cute, undefined = 💀

DtWidgetInfo [-h]  [widgetHandle]

No arguments: the list of active widget handles gets written to standard output. Arguments: they should represent widget handles, and in that case the name of the associated widget is written to standard output. Match made. 🫶

---

🌸 Convenience Functions 🌸

Bestie. The XCDE system ships a whole file of dtksh convenience functions, and it is itself a shell script full of shell functions that may be useful to a shell programmer. These functions do the frequently-used operations for you. That includes functions for quickly creating certain kinds of dialogs (help, error, warning, and so on), plus a function that makes it easy to build a whole collection of buttons, and functions that make configuring the constraint resources for a child of a form widget way less of a whole thing.

Ngl, you are not required to use these convenience functions. They're supplied purely to make it easier for developers to write shorter and more readable shell scripts. Use them or don't, no cap.

Before a shell script can touch these functions, it has to include the file that contains them first. They live in /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/lib/dtksh/DtFuncs.dtsh, and you pull them in with this notation:

. /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/lib/dtksh/DtFuncs.dtsh

---

🎀 DtkshAddButtons

This convenience function adds one or more buttons of the same kind into a composite widget. Most frequently it's used to add a collection of buttons into a menupane or a menubar. It's giving assembly line, but make it ✨aesthetic✨.

DtkshAddButtons [parent widgetClass label1 callback1]  [label2 callback2
...]

DtkshAddButtons [-w]  [parent widgetClass variable1 label1 callback1]
[variable2 label2 callback2 ...]

The -w option means the convenience function should return the widget handle for each of the buttons it creates. That widget handle comes back to you in the specified environment variable. Obsessed. 💖

The widgetClass argument can be set to any one of the following, and it defaults to XmPushButtonGadget if you don't specify one:

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 (living inside a form widget) so that the carriage-return key does not activate the default button within the form. Instead, carriage-return moves the focus to the next text widget within the form. Super useful when a window contains a series of text widgets plus the default button, and that button shouldn't fire until the user hits carriage-return while the focus is sitting in the last text widget. Delayed gratification, but for keyboards. ⌨️

DtkshSetReturnKeyControls [textWidget nextTextWidget formWidget
defaultButton]

The textWidget argument specifies the widget to configure so it catches the carriage-return key and forces focus to move on to the next text widget (as indicated by the nextTextWidget argument). The formWidget argument specifies the form containing the default button, and it must be the parent of the two text widgets, fr fr. The defaultButton argument says 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 specifying certain classes of form constraints. They give you a convenient way to attach a component to one edge of another component, and you use them when you're constructing the resource list for a widget. Under the hood this behavior is accomplished using the ATTACH_WIDGET constraint. Iconic behavior, honestly. 👑

DtkshUnder [widgetId]  [offset]

DtkshOver [widgetId]  [offset]

DtkshRightOf [widgetId]  [offset]

DtkshLeftOf [widgetId]  [offset]

The widgetId argument specifies the widget the current component gets attached to. The offset value is optional, and it defaults to zero if you don't specify one. Zero. Default. Noted. 📝

Example:

XtCreateManagedWidget BUTTON4 button4 pushButton $FORM         labelString:"Exit" $(DtkshUnder $BUTTON2)         $(DtkshRightOf $BUTTON3)

---

🌈 DtkshFloatRight, DtkshFloatLeft, DtkshFloatTop, DtkshFloatBottom

These convenience functions simplify specifying certain classes of form constraints. They're a convenient way to position 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. It may still grow or shrink though, depending on the other form constraints you've specified for that component. This behavior is accomplished using the ATTACH_POSITION constraint. Floating like it pays rent. 🦋

DtkshFloatRight [position]

DtkshFloatLeft [position]

DtkshFloatTop [position]

DtkshFloatBottom [position]

The optional position argument specifies the relative position that the indicated edge of the component gets positioned to. A default position is used if you don't specify one.

Example:

XtCreateManagedWidgetBUTTON1 button1 pushButton         $FORM labelString:"Ok" $(DtkshUnder $SEPARATOR)         $(DtkshFloatLeft 10) $(DtkshFloatRight 40)

---

⭐ DtkshAnchorRight, DtkshAnchorLeft, DtkshAnchorTop, DtkshAnchorBottom

These convenience functions simplify specifying certain classes of form constraints. They give you 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. Depending on the other form constraints set on this component, though, the component may still grow or shrink in size. This behavior is accomplished using the ATTACH_FORM constraint. Anchored. Unbothered. Moisturized. 💅

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 you don't specify an offset, zero is used.

Example:

XtCreateManagedWidget BUTTON1 button1 pushButton         $FORM labelString:"Ok" $(DtkshUnder $SEPARATOR)         $(DtkshAnchorLeft 10) $(DtkshAnchorBottom 10)

---

🔥 DtkshSpanWidth, DtkshSpanHeight

These convenience functions simplify specifying certain classes of form constraints. They give you a convenient way to configure a component so it spans either the full height or the full 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 the attachments. Full span, main character energy. 👑

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 you don't specify an offset, zero is used.

Example:

XtCreateManagedWidget SEP sep separator $FORM $(DtkshSpanWidth 1 1)

---

🫶 DtkshDisplayInformationDialog, DtkshDisplayQuestionDialog, DtkshDisplayWarningDialog, DtkshDisplayWorkingDialog, DtkshDisplayErrorDialog

(The original lists these like so, stray quote and all — keeping it true to source, bestie:)

DtkshDisplayInformationDialog, DtkshDisplayQuestionDialog, DtkshDisplayWarningDialog,
DtkshDisplayWorkingDialog, DtkshDisplayErrorDialog"

These convenience functions create a single instance of each of the Motif feedback dialogs. If an instance of the type of dialog you asked for already exists, it gets reused — no duplicates, we're sustainable here. 🌱

The parent of the dialog comes 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 comes back in one of these environment variables:

• DTKSH_ERROR_DIALOG_HANDLE
• DTKSH_QUESTION_DIALOG_HANDLE
• DTKSH_WORKING_DIALOG_HANDLE
• DTKSH_WARNING_DIALOG_HANDLE
• DTKSH_INFORMATION_DIALOG_HANDLE

Real talk: when you're attaching callbacks to the dialog buttons, the application should not destroy the dialog. Just unmanage it so it can be used again later. If you absolutely must destroy it, then clear the associated environment variable too, so the convenience function doesn't try to reuse a dialog that's gone. 😭

DtkshDisplay*Dialog title message [okCallback closeCallback
helpCallback dialogStyle]

The Ok button is always managed, and by default it unmanages the dialog. The Cancel and Help buttons are only managed when you supply a callback 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 type of help dialog you asked for already exists, it gets reused. The parent of the dialog comes 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 these environment variables:

• DTKSH_HELP_DIALOG_HANDLE
• DTKSH_QUICK_HELP_DIALOG_HANDLE

If you do need to destroy a help dialog, the application should also clear the associated environment variable, so the convenience function doesn't go trying to reuse a dialog that isn't there anymore. Clean up after yourself, periodt. 🧹

DtkshDisplay*HelpDialog title helpType helpInformation [locationId]

okay so the meaning of the arguments depends on the value you gave for the helpType argument, and here’s the mapping bestie:

• HELP_TYPE_DYNAMIC_STRING — helpInformation is the help string; locationId is &<not used>.
• HELP_TYPE_FILE — helpInformation is the help file name; locationId is &<not used>.
• HELP_TYPE_MAN_PAGE — helpInformation is the manual page name; locationId is &<not used>.
• HELP_TYPE_STRING — helpInformation is the help string; locationId is &<not used>.
• HELP_TYPE_TOPIC — helpInformation is the help volume name; locationId is the help topic location ID.

Example, slay:

DtkshDisplayHelpDialog "Help On Dtksh" HELP_TYPE_FILE "helpFileName"

🎀 Dtksh App-Defaults File 🎀

The dtksh app-defaults file is named dtksh, and it lives in a location based on this path description:

/nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/app-defaults/&<LANG>

The only info inside this app-defaults file is the inclusion of the standard desktop base app-defaults file. The contents of the dtksh app-defaults file are literally:

#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. So 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 of 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(3), 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

🔥 EXIT STATUS 🔥

See ksh-cde(1).

🫠 CONSEQUENCES OF ERRORS 🫠

See ksh-cde(1).

🌈 APPLICATION USAGE 🌈

✨ Initializing The Toolkit Environment ✨

Before any of the Xlib, Xt or Motif commands can be invoked, the shell script must first initialize the Xt toolkit by invoking the XtInitialize command, which returns an 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 🫶

Okay so session management is the whole vibe where applications can save their current state when the user ends 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:

#! /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/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
                        "/nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/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 gives you 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

🚨 Important: The file descriptor returned by catopen must be closed using catclose, and not using the ksh-cde 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 ✨

ok so this is the part where dtksh lets you mess with widget translations — and by "mess with" i mean augment them, override them, and remove them 💅 pretty much exactly how it works in the C programming environment, no cap.

In C, an app installs a whole set of translation action procedures, and then those get attached to specific sequences of events. (quick refresher bestie: a translation = an event sequence + the action procedure that goes with it 🎀)

Translations inside dtksh work the same way, with one tiny difference: there's only a single action procedure available. That's it. One. Just the one 🫶

And that one action procedure is named ksh_eval — she's the main character here 👑. She takes whatever arguments you hand her, interprets them as dtksh commands, and evaluates them the moment the translation gets triggered. iconic behaviour honestly.

Here's a little shell script segment showing how translations get used in the wild:

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")'

see what's happening? BUTTON1 gets her translations augmented with #augment (so &<EnterNotify> and &<Btn1Down> both get layered on top of whatever was already there) 🌸 and then BUTTON2 gets hers overridden with #override, where &<Btn1Down> now fires ksh_eval("BtnDownProcedure 2") instead. two buttons, two totally different vibes, both slaying ✨

---

🦋 EXAMPLES 🦋

None.

like... literally none. that's the whole section. none. we move 💀

---

🌈 SEE ALSO 🌈

• ksh-cde(1) — go read that one too bestie, iykyk 💖

---

ok that's the whole page, we made it to the end 🎉 mwah, go write some absolutely unhinged dtksh scripts and remember: ksh_eval is your only action procedure, so treat her right 🫶

this lil manual page is dtksh(user cmd) — that's the source/version tag and the date stamp, right there at the bottom, doing its quiet little thing. periodt 💅✨