DTACTIONFILE(4)

📦
version 2.5.3 · 2 versions
, in nixos 26.05

💖 dtactionfile(special file) 💖

okay bestie, this is the manual page for dtactionfile, the special file situation that explains how desktop action definition records work. it's giving “blueprint energy” for actions, and we're gonna keep every single detail, no cap. 🫶

🦋 NAME 🦋

dtactionfile — define the content of desktop action definition records. literally the whole point. periodt. ✨

🎀 SYNOPSIS 🎀

set DtDbVersion=version_number
set VariableName=variable_value
ACTION  action_name
{
        # Comment
        FieldName field_value
        FieldName field_value
        ...
}

🌸 DESCRIPTION 🌸

okay so XCDE actions define the behavior of icons, front panel controls and operations on data objects. iconic behavior, honestly. actions are defined in a set of text files with the .dt suffix. each action definition consists of the word ACTION followed by an action name and a list of Field and Value pairs (one per line) on lines by themselves and enclosed in brackets. yes, one field/value pair per line, on its own line, and the whole list wrapped in brackets. slay. 🎀

these text files may also contain data typing information as described in dtdtsfile(4). (see dtdtfile(4) for the general syntax and location of the actions and data types database.) lowkey important, don't skip it. 💅

actions are of one of the following classes: command actions, ToolTalk message actions or map actions. these action classes are described in the following sections. let's get into it. 🦋

✨ Command Actions ✨

command actions are identified by a TYPE COMMAND field. this field defines an execution string to invoke and a set of related information, such as the current working directory for the command and the host where the command should be executed. the following field names are unique to command actions: EXEC_STRING, EXEC_HOST, CWD, WINDOW_TYPE and TERM_OPTS. those are the command-action exclusives, bestie. 👑

✨ ToolTalk Message Actions ✨

ToolTalk message actions are identified by a TYPE TT_MSG field. this field defines a ToolTalk message to be sent. the following fields are unique to ToolTalk message actions: TT_CLASS, TT_SCOPE, TT_OPERATION, TT_FILE, TT_ARGn_MODE, TT_ARGn_VTYPE, TT_ARGn_REP_TYPE and TT_ARGn_VALUE. yes, all of them. no cap. 🫶

✨ Map Actions ✨

map actions are identified by a TYPE MAP field. this field does not define any specific behavior; instead, this field specifies a different action name that should be invoked in place of the original action. multiple map actions can be chained together, but the chain must ultimately terminate in a non-map action. so like, you can pass the vibe along, but the chain has to end somewhere real. and the following field is unique to map actions: MAP_ACTION. periodt. 💅

✨ Common Fields ✨

in addition to the unique action fields listed above, all actions support the following fields: LABEL, ICON, DESCRIPTION, ARG_CLASS, ARG_MODE, ARG_TYPE, ARG_COUNT and TYPE. these are the communal icons of the action world. 🌈

✨ Keywords ✨

the value string for certain action fields may reference special keywords enclosed within percentage character (%) delimiters. these keywords are evaluated when the action is invoked and replaced with the appropriate value. in fields that do not evaluate keywords, the keyword is taken literally. valid keywords are:

  • %DatabaseHost% — the name of the host where the action definition file is located. this hostname is specified by the host portion of the host:/ path searchpath used to find the action.
  • %DisplayHost% — the name of the host where the X server displaying the XCDE session is running.
  • %LocalHost% — the name of the host where the application invoking the action is executing.
  • %SessionHost% — the name of the host where the controlling login manager (dtlogin(1)) runs.

those are the housekeeping hosts, and they matter. 🏠✨

✨ Argument References ✨

arguments passed to actions can be referenced in certain action fields using special argument keywords enclosed within percent character (%) delimiters. these argument keywords are evaluated when the action is invoked and replaced with the appropriate value. in fields that do not evaluate keywords, the keyword is taken literally. the valid argument keywords are:

  • %Arg_n% — the nth (starting with 1) argument of the action. if the action was invoked with fewer than n arguments, the value of the keyword is NULL.
  • %Args% — all remaining arguments of the action. if any arguments of the action have already been referenced within this field by an %Arg_ n% keyword, those arguments are not referenced a second time by %Args%.
  • % — prompt the user for a value, using prompt as the label of a text field.
  • %Arg_n — the nth (starting with 1) argument of the action. if the action was invoked with fewer than n arguments, prompt the user for a value using prompt as the label of a text field.

if a keyword references the name of a file argument, the value of the keyword is expanded to an absolute pathname prior to substitution. in addition, if the file name is to be passed to a remote system, the file name is first mapped appropriately (see tt_file_netfile(3) and tt_netfile_file(3)). remote-file mapping: handled. 💅

if the keyword references a buffer argument, the buffer data is placed in a temporary file and the name of the temporary file is substituted, as described above. some action fields provide direct support for data buffers and do not require use of a temporary file. this behavior is noted in the description of the appropriate fields. so don't assume every buffer needs a temp file, iykyk. 🧚

if the keyword references a string obtained from the user, it is treated as a simple string and the value substituted without any transformation. no extra glow-up, just the string. ✨

argument references can be forced to be treated as file names or simple strings by using the (File) or (String) qualifier immediately after the opening % of the keyword. for example:

%(String)Arg_n%
%(File)"prompt"%

if an action is invoked with more than one argument, and the action definition only references one or zero arguments, the action is iteratively invoked with each of the supplied arguments. if the action definition references more than one argument, any extra arguments are ignored. that's the rule, bestie. don't fight it. 🫶

✨ Action Selection ✨

multiple actions can be defined with the same name. when the action is invoked, the appropriate action definition is chosen based on the number and class of arguments supplied. for example, the Open action may invoke dtpad(1) if a text file is supplied as an argument, or it may invoke dticon(1) if a bitmap file argument is supplied. main character action selection energy. 👑

the ARG_COUNT, ARG_CLASS, ARG_MODE and ARG_TYPE fields specify the number, mode and types of arguments that are accepted by a particular action. because these fields can have shell pattern-matching values such as *, it is possible that the action database contains multiple actions that have the same name and are all capable of accepting the arguments that are supplied. in this case, the following precedence rules are used to choose a single action definition to invoke:

  • actions with more specific attribute values take precedence over more general attribute values.
  • for the ARG_COUNT field, an exact numerical value (N) is more specific than a less-than range (&<N). a less-than range (&<N) is more specific than a greater-than range (>N). and a greater-than range (>N) is more specific than a shell pattern-matching character (*).
  • for the ARG_CLASS and ARG_TYPE fields, a single item is more specific than a list of items and a list of items is more specific than a shell pattern-matching *.
  • for the ARG_MODE field, w (writable) and !w (not writable) are more specific than a shell pattern-matching *.
  • the fields have the following precedence, from high to low: ARG_CLASS, ARG_TYPE, ARG_MODE, ARG_COUNT.
  • if two action definitions have equal specificity, the action definition appearing first in the database load order takes precedence. database directories are loaded in the order specified by the DTDATABASESEARCHPATH environment variable, and are loaded in the collation order of their file names.

so yeah, specificity is the vibe check, and load order breaks the tie. 💅

🎀 ARG_CLASS Field 🎀

the ARG_CLASS field is optional for all types of actions. this field specifies the class of arguments the action accepts. if an action is invoked with more than one argument, the class of only the first argument is checked against the value of the ARG_CLASS field. the valid values for this field are:

  • BUFFER — the action accepts arguments that are blocks of data held in memory.
  • FILE — the action accepts arguments that are file names.
  • * — the action is defined for all classes of arguments.

a comma-separated list of valid values is also allowed and specifies that the action accepts arguments of any of the listed classes. yes, you can list them. we love options. 🦋

if an action is defined to accept a buffer argument, yet the implementation of the action requires a file name, the buffer is automatically converted into a temporary file for the action to use. see the description of the DtTmpDir resource for information on configuring the location of these temporary files. buffer-to-temp-file pipeline: automatic. iconic. ✨

keywords are not evaluated in the ARG_CLASS field. the default value of the ARG_CLASS field is *. periodt. 💅

🎀 ARG_COUNT Field 🎀

the ARG_COUNT field is optional for all types of actions. the ARG_COUNT field specifies the number of arguments that the action accepts. the valid values for this field (where N denotes any non-negative integer) are:

  • N — the action accepts exactly N arguments.
  • &<N — the action accepts any number of arguments less than N.
  • >N — the action accepts any number of arguments greater than N.
  • * — the action accepts any number of arguments.

keywords are not evaluated in the ARG_COUNT field. the default value of the ARG_COUNT field is *. so if you don't specify, it's *, bestie. 🫶

🎀 ARG_MODE Field 🎀

the ARG_MODE field is optional for all types of actions. this field specifies the mode of arguments the action accepts. if an action is invoked with more than one argument, the mode of only the first argument is checked against the value of the ARG_MODE field. the valid values for this field are:

  • w — the action accepts arguments that are writable by the user.
  • !w — the action accepts arguments that are not writable by the user.
  • * — the action is defined for all classes of arguments.

keywords are not evaluated in the ARG_MODE field. the default value of the ARG_MODE field is *. writable or not writable, the vibe is specified here. 💅

🎀 ARG_TYPE Field 🎀

the ARG_TYPE field is optional for all types of actions. this field specifies the types of arguments the action accepts. if the action is invoked with more than one argument, the type of only the first argument is checked against the value of this field. valid values for this field are * (all data types are accepted), a single data type name or a comma-separated list of data types. the set of valid data types are those defined by DATA_ATTRIBUTE records in the data typing database. (see dtdtsfile(4) for more information.) so like, the data typing database is the source of truth here. 🌸

keywords are not evaluated in the ARG_TYPE field. the default value of the ARG_TYPE field is *. and that's the type check, bestie. 🎀

🌸 CWD Field 🌸

Okay so the CWD field is optional for literally every type of action, no gatekeeping here 💅. What it does? It tells the system which current working directory to use when the execution string gets invoked. Valid values are any absolute pathname, periodt.

If you don't specify it, the current working directory for the execution string gets figured out like this:

  • If the application invoking the action specifies a current working directory, that directory is used. 🫶
  • If arguments are supplied to the action and the first argument is a directory, that directory is used.
  • If arguments are supplied to the action and the first argument is a file, the directory where the file is located is used.
  • The current working directory of the application invoking the action is used. (Last resort, bestie 😭)
Real talk: keywords are not evaluated in the CWD field. Don't try it.

🎀 DESCRIPTION Field 🎀

DESCRIPTION is optional for COMMAND actions — it's the little blurb that's suitable for presenting to a user who's asking for info about the action. So like, the vibe description yk?

It should contain no formatting information such as tab or newline characters — keep it clean bestie, the application that presents the information to the user is the one that formats it.

Keywords are not evaluated in the DESCRIPTION field, and there's no default value. iykyk.

🦋 EXEC_HOST Field 🦋

EXEC_HOST is optional for COMMAND actions and it specifies the host where the execution string should be invoked. Valid values include actual hostnames plus any of the hostname keywords. ✨

If you hand it a comma-separated list of hostnames, execution is attempted on each of the hosts in the order specified, until execution succeeds. (Little trial-and-error arc, love that for us.)

Keywords are evaluated in the EXEC_HOST field. The default value is %DatabaseHost%,%LocalHost%. (Peep the description of the ExecutionHosts resource if you wanna change that default.)

🔥 EXEC_STRING Field 🔥

EXEC_STRING is required for COMMAND actions — it's the actual execution string to be invoked. The string is parsed using the same quoting rules as defined by sh(1); however, the execution string is not automatically passed to any shell. So if your execution string needs shell features like redirection of standard input, redirection of standard output, or pipes, you gotta specify the appropriate shell explicitly in the execution string. For example:

EXEC_STRING       sh -c 'ls -l | more'

Keywords are evaluated in the EXEC_STRING field. There is no default value for the EXEC_STRING field.

⭐ ICON Field ⭐

ICON is optional for all types of actions and it specifies the name of an icon that represents the action. Cute little visual moment 🎀.

Icons are found by using the standard XCDE icon search path, so the value can be either an absolute pathname (for example, /foo/icons/myicon.bm), a relative pathname (for example, icons/myicon.bm) or a partial filename (for example, myicon). Partial filenames are preferred because they allow the XCDE icon search path to find the icon with the optimum size and depth for the current environment. Icon slay 💅.

Keywords are not evaluated in the ICON field. The default value is Dtactn. (See the description of the ActionIcon resource for info on changing that default.)

🌈 LABEL Field 🌈

LABEL is optional for all types of actions and it's the user-visible label for the action. When actions are presented to the user, the localized LABEL field is used to identify the action instead of the non-localized action name. It's giving name tag at a party 🫶.

Keywords are not evaluated in the LABEL field. The default value of the LABEL field is the name of the action.

💜 MAP_ACTION Field 💜

MAP_ACTION is required for MAP actions — it specifies the name of an action that should be invoked in place of the current action. The specified action is invoked with the same set of arguments that were passed to the original action. (Passing the baton, iconic behavior honestly.)

Keywords are not evaluated in the MAP_ACTION field. There is no default value for the MAP_ACTION field.

🧚 TERM_OPTS Field 🧚

TERM_OPTS is optional for COMMAND actions. It specifies command-line options that are passed to the terminal emulator for all COMMAND actions that are terminal based. (That means any COMMAND action other than those that specify WINDOW_TYPE NO_STDIO.) These command-line options are typically used to specify a unique terminal-window geometry, font, color or title. Aesthetic customization, we love to see it ✨.

Big warning energy: the value of the TERM_OPTS field must be an option string in a form the terminal emulator supports, and it must only affect the appearance of the terminal window. Options such as -e, which affect the behavior of the terminal window, must not be used. Nope nope nope 🚫.

Keywords are evaluated in the TERM_OPTS field. The default value is

-title action_label

where action_label is the LABEL field for the action. See dtterm(1) (or xterm(1)) for the meaning of -title.

🍓 TT_ARGn_MODE Field 🍓

TT_ARGn_MODE is optional for TT_MSG actions. It specifies the value of the ToolTalk mode attribute for the nth message argument, where n is zero for the first message argument. (Yes, zero-indexed, we're programmers bestie 😭.)

Valid values for this field are: TT_IN, TT_INOUT and TT_OUT.

(See Tt/tt_c.h for a description of these values.)

Keywords are not evaluated in the TT_ARGn_MODE field. There is no default value for the TT_ARGn_MODE field.

🌸 TT_ARGn_REP_TYPE Field 🌸

TT_ARGn_REP_TYPE is optional for TT_MSG actions. It specifies the representation type of the nth ToolTalk message argument, where n is zero for the first message argument. Valid values are:

  • TT_REP_UNDEFINED — If TT_ARGn_VALUE references a buffer argument, the representation type is a buffer; otherwise, it is a string.
  • TT_REP_INTEGER — The representation type is an integer.
  • TT_REP_BUFFER — The representation type is a buffer.
  • TT_REP_STRING — The representation type is string.

Keywords are not evaluated in the TT_ARGn_REP_TYPE field. The default value is TT_REP_UNDEFINED.

👑 TT_ARGn_VALUE Field 👑

TT_ARGn_VALUE is optional for TT_MSG actions, but bestie listen: if there's no corresponding TT_ARGn_MODE field, the TT_ARGn_VALUE field is ignored. If there is a TT_ARGn_MODE field, then TT_ARGn_VALUE specifies the value of the nth ToolTalk message argument, where n is zero for the first message argument. And if there's a TT_ARGn_MODE field with no corresponding TT_ARGn_VALUE field, the value of the *n*th ToolTalk message argument is set to NULL.

The value of the TT_ARGn_VALUE field must be a single string or action argument. Keywords that reference a single action argument are evaluated in this field, however %Args% is not allowed as it references multiple action arguments. There is no default value for the TT_ARGn_VALUE field.

🦋 TT_ARGn_VTYPE Field 🦋

TT_ARGn_VTYPE is required to accompany any TT_ARGn_MODE fields in TT_MSG actions. It specifies the value of the ToolTalk vtype attribute of the nth message argument, where n is zero for the first message argument.

If this field references an argument keyword, the MEDIA attribute of the specified argument is used. If the MEDIA attribute is not defined, the DATA_ATTRIBUTE name of the data type is used. (Fallback chain, we stan 🌟.)

Keywords are evaluated in the TT_ARGn_VTYPE field. There is no default value for the TT_ARGn_VTYPE field.

💀 TT_CLASS Field 💀

TT_CLASS is required for TT_MSG actions. It specifies the value of the ToolTalk class message field. Valid values:

  • TT_NOTICE — The action defines a ToolTalk notification message.
  • TT_REQUEST — The action defines a ToolTalk request message.

Keywords are not evaluated in the TT_CLASS field. There is no default value for the TT_CLASS field.

🎀 TT_FILE Field 🎀

TT_FILE is optional for TT_MSG actions. It specifies the value of the ToolTalk file message field. The value must be a single file name and can either be a specific file name (for example, /tmp/foo) or an argument keyword (for example, %Arg_1%). %Args% is not allowed because it references multiple action arguments.

Heads up: if an argument keyword is specified and the corresponding argument is not a file (that is, it is a buffer), the action invocation fails. 😭

Keywords are evaluated in the TT_FILE field. There is no default value for the TT_FILE field; if it is not set, the file attribute of the ToolTalk message is set to NULL.

🌟 TT_OPERATION Field 🌟

TT_OPERATION is required for TT_MSG actions. It specifies the value of the ToolTalk operation message field. Typical values are operations such as Display or Edit that are defined by the Media Exchange Message Set. (Okay but Edit is such a main character operation 💅.)

Keywords are not evaluated in the TT_OPERATION field. There is no default value for the TT_OPERATION field.

🌈 TT_SCOPE Field 🌈

TT_SCOPE is required for TT_MSG actions. It specifies the value of the ToolTalk scope message field. (See Tt/tt_c.h for a description of these values.) Valid values: TT_BOTH, TT_FILE, TT_FILE_IN_SESSION and TT_SESSION.

Keywords are not evaluated in the TT_SCOPE field. There is no default value for the TT_SCOPE field.

🔥 TYPE Field 🔥

TYPE is optional for COMMAND actions and required for MAP or TT_MSG actions. It specifies the type of behavior defined by the action. Valid values:

  • COMMAND — The action invokes a command.
  • MAP — The action specifies a different action name to invoke in place of the current action.
  • TT_MSG — The action defines a ToolTalk message to be sent.

Keywords are not evaluated in the TYPE field. The default value of the TYPE field is COMMAND.

✨ WINDOW_TYPE Field ✨

WINDOW_TYPE is optional for COMMAND actions. It specifies the type of windowing support the execution string requires. Valid values:

  • NO_STDIO — No windowing support is required. Appropriate for execution strings that have no output, or that are X Windows applications.
  • PERM_TERMINAL — The execution string requires a terminal window. When the execution string exits, the terminal window is left open until the user explicitly closes it. Appropriate for applications that write their output to standard output and then terminate, such as ls(1). 🫶
  • TERMINAL — the execution string needs a terminal window, periodt. When the execution string exits, the terminal window closes. If the execution string exits “quickly” (peep the waitTime resource description), the terminal window stays open so you can see any error messages that were written to standard output or standard error. This value is the one for full-screen terminal apps like the vi(1) editor. iconic terminal behavior, no cap 💅

Keywords are not evaluated in the WINDOW_TYPE field. The default value of the WINDOW_TYPE field is PERM_TERMINAL.

✨ RESOURCES ✨

These resources control how actions behave. Set them for the application that is invoking the action. You can set them for all applications that invoke actions by omitting the application name or class name, bestie 🫶

X11 Resources That Modify Action Behavior

Name → Class → Type → Default, in that exact order:

  • actionIcon — Class: ActionIcon; Type: string; default: Dtactn.
  • dtEnvMapForRemote — Class: DtEnvMapForRemote; Type: string; default: DTAPPSEARCHPATH:DTHELPSEARCHPATH:DTDATABASESEARCHPATH:XMICONSEARCHPATH:XMICONBMSEARCHPATH.
  • dtexecPath — Class: DtexecPath; Type: string; default: /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/bin/dtexec.
  • dtTmpDir — Class: DtTempDir; Type: string; default: $HOME/.dt/tmp.
  • executionHostLogging — Class: ExecutionHostLogging; Type: string; default: False.
  • executionHosts — Class: ExecutionHosts; Type: string; default: %DatabaseHost%, %LocalHost%.
  • localTerminal — Class: LocalTerminal; Type: string; default: dtterm.
  • remoteTerminals — Class: RemoteTerminals; Type: string; default: None.
  • waitTime — Class: WaitTime; Type: number; default: 3.
also the raw source had this table-layout tag: tgroup dispwid="6.19in" — troff fairy dust, don’t worry about it 🧚

actionIcon

Specifies the default value of the ICON field for actions that do not define that field. The default value of this resource is Dtactn.

dtEnvMapForRemote

Specifies a colon-separated list of environment variable names. Each variable contains a colon-separated list of pathnames to be mapped for remote actions (see tt_file_netfile(3) and tt_netfile_file(3)).

Only environment variables in the user’s current environment (see environ(5)) are mapped. Supplemental environment variables — like the ones added by dtspcdenv(4), for example — are not mapped.

If a pathname contains substitution characters, only the portion of the path up to the first percent character is mapped, with the remaining portion appended to the resulting mapped portion. For example, if NLSPATH is set to /system/nlslib/%L/%N.cat, it maps to /net/host/system/nlslib/%L/%N.cat. slay, path mapping 🌈

dtexecPath

Specifies the location of the dtexec(1) command that is used for terminal-based actions. The default value is /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/bin/dtexec.

dtTmpDir

Specifies the full pathname of the directory to be used for holding temporary files created during action invocation. The directory must be visible to remote hosts used for action execution.

executionHostLogging

Turns detailed logging to the user’s $HOME/.dt/errorlog of action invocation events on and off. The default value is False, which disables logging. Logging is enabled if this resource is set to True.

executionHosts

Specifies the default value of the EXEC_HOST field for COMMAND actions that do not define the field. The default value is %DatabaseHost%,%LocalHost%.

localTerminal

Specifies an alternative terminal emulator for terminal-based actions that execute locally. Any terminal emulator specified by this resource must support the -title and -e options as described in dtterm(1). The default value is dtterm(1).

remoteTerminals

Specifies the terminal emulator to use for terminal-based actions that execute on the named system. The value of this resource is a comma-separated list of the form host:terminal-path, where terminal-path is the terminal emulator used when invoking terminal-based actions on host host. The default terminal emulator used for any host not specified by this resource is the emulator specified by the localTerminal resource.

waitTime

Specifies the time threshold used for COMMAND actions that specify WINDOW_TYPE TERMINAL. If the command exits in less than waitTime seconds, the terminal window is left open. The default value is 3.

✨ EXAMPLES ✨

The following action is defined to pipe its argument through the pr(1) and lp(1) commands:

       ACTION PrintText
       {
               ICON            printer
               DESCRIPTION     Paginate and print a text file to the                         default printer.
               ARG_TYPE        Text
               TYPE            COMMAND
               EXEC_STRING     sh -c 'pr %Arg_1"File to print:"% | lp'
               WINDOW_TYPE     NO_STDIO
       }

The following action defines that Open on Text files use the EditText action:

       ACTION Open
       {
               ARG_TYPE        Text
               TYPE            MAP
               MAP_ACTION      EditText
       }

The following action is defined to send the ToolTalk Display request message for non-writable objects:

       ACTION Display
       {
               ARG_CLASS               BUFFER
               ARG_MODE                !w
               TYPE                    TT_MSG
               TT_CLASS                TT_REQUEST
               TT_SCOPE                TT_SESSION
               TT_OPERATION            Display
               TT_ARG0_MODE            TT_IN
               TT_ARG0_VTYPE           %Arg_1%
               TT_ARG0_VALUE           %Arg_1%
       }

🌸 APPLICATION USAGE 🌸

Errors encountered when loading database files are written to the user’s $HOME/.dt/errorlog. Errors encountered in the value of an action field cause the field to be rejected. If the field is a required field, the entire action definition is rejected. Errors encountered when an action is invoked cause an error dialog to be displayed to the user. do not ignore the errorlog, bestie, it’s literally trying to tell you something 😭

🦋 SEE ALSO 🦋

okay bestie, that’s the whole page 💖 source/version footer: dtactionfile(special file) — date? this excerpt only gave us the title, so I’m not gonna invent one. The vibes are timeless anyway. 🫶✨

📦 where this page comes from