DTACTIONINVOKE(3)

okay bestie, this is DtActionInvoke(3) — the DtActionInvoke library call, and it’s literally giving “your app can invoke XCDE actions on file or buffer arguments” main character energy. Applications can register a callback for receiving action-done status and return arguments. Obsessed. 💅✨

🌸 NAME 🌸

DtActionInvoke — invoke a XCDE action. 💖

✨ SYNOPSIS ✨

#include &<Dt/Action.h>
DtActionInvocationID DtActionInvoke(
Widget w,
char *action,
DtActionArg *args,
int argCount,
char *termOpts,
char *execHost,
char *contextDir,
int useIndicator,
DtActionCallbackProc statusUpdateCb,
XtPointer client_data);

🦋 DESCRIPTION 🦋

Before DtActionInvoke can run successfully, the actions and data types databases have to be initialized and loaded — use DtInitialize(3) and DtDbLoad(3), no cap. It’s lowkey non-negotiable. 😭

Here’s the argument lineup, bestie:

• w — the widget that becomes the parent of any dialogs or error messages resulting from action invocation. It should be a top-level application shell widget that continues to exist for the action’s expected lifetime. This argument must have a non-NULL value. 🫶
• action — the name of the action to be invoked. The action database may define more than one action with the same name. The action selected for a particular invocation depends on the class, type, and number of arguments provided (as described in dtactionfile(4)). This argument must have a non-NULL value. 👑
• args — an array of action argument structures containing information about the arguments for this action invocation. If there are no arguments, the value of args must be NULL. The items in this array are assigned to the option argument keywords referenced in the action definition (see dtactionfile(4)). The nth item is assigned to keyword %Arg_ n%. For example, the second item is assigned to %Arg_2%. 🎀
• argCount — the number of action arguments provided in the array that args references. 🔢
• termOpts — a string providing special execution information for the terminal emulator used for COMMAND actions of WINDOW_TYPE TERMINAL or PERM_TERMINAL. (See dtactionfile(4).) This string must be quoted if it contains embedded blanks. The application uses this string to pass on title, geometry, color, and font information to the terminal emulator. This information must be in a form the expected terminal emulator recognizes. This argument can be NULL. 🖥️
• execHost — a string identifying a preferred execution host for this action. The execHost specified here supersedes the list of execution hosts defined in the action definition. If execHost is NULL, the execution host for the action is obtained from the action definition as described in dtactionfile(4). 🌐
• contextDir — a string identifying a fallback working directory for the action. File name arguments are interpreted relative to this directory, which must reside in the local file name space (for example, /usr/tmp or /net/hostb/tmp). This value is only used if the action definition does not explicitly specify a working directory in the CWD field of the action definition. If contextDir is NULL, the current working directory of the action is obtained from the action definition, as described in dtactionfile(4). 📁
• useIndicator — if this flag is zero, DtActionInvoke does not provide any direct indication to the user that an action has been invoked. If useIndicator is non-zero, the user is notified via some activity indicator (for example, a flashing light in the front panel) that an action has been invoked. This indication persists only until the invocation of the action completes (in other words, until the action begins running). 🚨
• statusUpdateCb — a callback that may be activated if the invoked actions have returnable status (for example, a TT_MSG(TT_REQUEST) returning DtACTION_DONE). At a minimum, a DtACTION_INVOKED status is returned when DtActionInvoked has finished processing and has completely invoked any resulting actions, and a DtACTION_DONE or equivalent done status is returned when all actions terminate. If statusUpdateCb is set to NULL, subsequent action status is not returned. (See Dt/Action.h - DtAction(5) for a list of all DtActionStatus codes, and see DtActionCallbackProc(3) for details on statusUpdateCb and a list of specific DtActionStatus codes it can return.) 📞
• client_data — optional data to be passed to the statusUpdateCb callback when invoked. 🎁

The DtActionInvoke function searches the action database for an entry that matches the specified action name, and accepts arguments of the class, type and count provided. It’s giving detective energy, but make it desktop. 🔍

If DtActionInvoke finds a matching action, the supplied arguments are inserted into the indicated action fields. If any missing action arguments have an associated prompt string, then a dialog box prompts the user to supply the arguments; otherwise, missing arguments are ignored. If too many arguments are supplied to an action requiring more than a single argument, a warning dialog is posted, allowing the action to be cancelled or continued, ignoring the extra arguments. If too many arguments are supplied to an action requiring zero or one arguments, then that action is invoked once for each of the supplied arguments. Arguments in the DtActionArg structure that may have been modified by the action are returned by the callback if a statusUpdateCb callback is provided. For DtActionBuffer arguments, the writable flag acts as a hint that the buffer is allowed to be modified and returned. 🧚

The DtActionBuffer structure contains at least the following members:

void      *bp        location of buffer
int       size       size of buffer in bytes
char      *type      optional type of buffer
char      *name      optional name of buffer
Boolean   writable   action is allowed to
                     modify and return the
                     buffer

The DtActionFile structure contains at least the following member:

char   *name   name of file

The DtActionArg structure contains at least the following members:

int              argClass   see argument class types (
                             ARG_CLASS field)
DtActionFile     u.file     union to a DtActionFile structure
DtActionBuffer   u.buffer   union to a DtActionBuffer structure

where argClass is DtACTION_FILE or DtACTION_BUFFER. The action service may set argClass to DtACTION_NULLARG for action arguments returned by a statusUpdateCb to indicate that the argument is not being updated or has been removed. DtACTION_NULLARG cannot be present in action arguments passed to DtActionInvoke. 🚫

The DtActionInvoke function accepts a pointer to an array of DtActionArg structures describing the objects to be provided as arguments to the action. The args structure can be modified or freed after DtActionInvoke returns. So yes, you can let it go after the call — no lingering attachment. 💨

A single call to DtActionInvoke may initiate several actions or messages. For example, if an action is given three files, but only needs one, three instances of the action are started, one for each file. As a result, a single returned DtActionInvocationID may represent a group of running actions, and subsequent execution management services (DtAction) calls operate on that group of actions. It’s a group chat, not a solo DM. 👯‍♀️

For DtACTION_BUFFER arguments, the action service first tries to type the buffer *bp using the name field (see dtdtsfile(4)). The name field would typically contain a value resembling a file name with an optional extension describing its type. If the name field is NULL, then the action service uses the type specified in the type field. If the type field is NULL, then the action service types the buffer *bp by content (see dtdtsfile(4)). If the name and type fields are both non-NULL, then the action service uses the name field for typing and ignores the type field. If the buffer pointer bp is NULL or size is equal to zero, a buffer with no contents is used in the resulting action. If returned, the buffer pointer bp is defined, and size is equal to or greater than zero. 🍓

When necessary, DtACTION_BUFFER arguments are automatically converted to temporary files prior to actual action invocation, and reconverted back to buffers after action termination (this is transparent to the caller). If a non-NULL name field is given, it is used in the construction of the temporary file name (for example, /myhome/.dt/tmp/name). If the use of name would cause a conflict with an existing file, or name is NULL, the action service generates a temporary file name. The permission bits on the temporary file are set according to the writable field and the IS_EXECUTABLE attribute from the action service associated with the type field. ✨

For DtACTION_FILE arguments, name is required. 💯

For DtACTION_BUFFER arguments, name cannot contain slash characters. ⚠️

Errors encountered are either displayed to the user in a dialog box or reported in the desktop errorlog file ($HOME/.dt/errorlog, unless configured otherwise). So if something goes feral, that’s where the receipts live. 🧾💀

RESOURCES 🎀

Caret1 — okay bestie, this is literally just sitting here at the top of the section with zero context, so we’re including it, no cap 💀.

This section is all about the X11 resources that DtActionInvoke recognizes. The resource class string always begins with an upper-case letter. The corresponding resource name string begins with the lower case of the same letter. These resources can be defined for all clients using the Action Library API by specifying *resourceName: value. For example, to set the terminal emulator to xterm(1) for all clients, the application can use *localTerminal: xterm. The resources can also be defined on a per client basis. For example, it can use Dtfile*localTerminal: xterm to set the terminal emulator to xterm(1) for the dtfile client only. (See dtactionfile(4).)

X11 Resources ✨

                               X11 Resources
       Name                  Class               Value Type   Default
       localterminal         LocalTerminal       string       ``Dtterm''
       remoteTerminals       RemoteTerminals     string       ``Dtterm''
       waitTime              WaitTime            number       3

• localterminal / LocalTerminal / string / default Dtterm — Defines an alternative local terminal emulator for Command actions of WINDOW_TYPE TERMINAL or PERM_TERMINAL to use. The default terminal emulator is dtterm(1).
• remoteTerminals / RemoteTerminals / string / default Dtterm — Defines a comma-separated list of host and terminal emulator pairs. When a remote COMMAND action is executed on one of the hosts in the list, the terminal emulator associated with that host is used for that command. The list is passed to the terminal emulator using the -e argument. (Thus, if another terminal emulator than dtterm is used, it must support the -e argument. See xterm(1).)
• waitTime / WaitTime / number / default 3 — Used to assign an alternative integer value, in seconds, to the threshold successful return time interval. If a COMMAND action of WINDOW_TYPE TERMINAL fails, the terminal emulator may be unmapped before the user has a chance to read the standard error from the failed command. This resource provides a workaround to this problem. If a TERMINAL window command exits before WaitTime seconds have elapsed, the terminal emulator window is forced to remain open, as if it were of TYPE PERM_TERMINAL. The default value of WaitTime is 3 seconds.

---

RETURN VALUE 🫶

Upon successful completion, the DtActionInvoke function returns a DtActionInvocationID. The ID can be used in subsequent execution management services (DtAction) calls to manipulate the actions while they are running. DtActionInvocationIDs are only recycled after many have been generated.

APPLICATION USAGE 🧚

The caller should allocate space for the array of structures describing the objects to be provided as arguments to the action. The caller can free the memory after DtActionInvoke returns.

Since DtActionInvoke spawns subprocesses to start local actions, the caller should use waitpid(2) instead of wait(2) to distinguish between processes started by the action service and those the caller starts.

EXAMPLES 🌸

Given the following action definition:

ACTION Edit
{
        LABEL           "Text Edit Action"
        ARG_CLASS       BUFFER, FILE
        ARG_TYPE        TEXT
        TYPE            COMMAND
        WINDOW_TYPE     TERMINAL
        EXEC_STRING     "textedit %Args%"
        DESCRIPTION     This action invokes the "textedit" command on
                        an arbitrary number of arguments.  A terminal
                        emulator is provided for this action's I/O.
                        EXEC_HOST and CWD are not specified so the
                        defaults are used for both quantities.
}

The following call invokes the action Edit on the arguments aap supplies:

        DtActionInvoke(w, "Edit", aap, 3, NULL, NULL, NULL, 1,
                       myCallback, myClientData);

The working directory for the action defaults to the current working directory. The execution host is the default execution host.

If the variable aap points to an array of ActionArg data structures containing the following information:

{
        argClass = DtACTION_FILE;
        struct {
            name="/myhome/file1.txt";
        } file;
}

{
        argClass = DtACTION_FILE;
        struct {
            name="file2.txt";
        } file;
}

{
        argClass = DtACTION_BUFFER;
        struct {
            bp=(void *) myEditBuffer;
            size=lengthOfMyEditBuffer;
            type=NULL;
            name="Doc1.txt"
            writable=TRUE;
        } buffer;
}

and the current working directory is /cwd, then the Edit action results in the execution string:

textedit /myhome/file1.txt /cwd/file2.txt /myhome/.dt/tmp/Doc1.txt

When the action completes, myCallback is called and the callback returns the buffer argument.

SEE ALSO 💜

• Dt/Action.h - DtAction(5)
• xterm(1)
• XtFree(3)
• XtMalloc(3)
• DtDbLoad(3)
• DtInitialize(3)
• DtActionCallbackProc(3)
• dtactionfile(4)
• dtdtfile(4)
• dtdtsfile(4).

Footer vibe check: the page signs off as DtActionInvoke(library call), and there is literally no date line in sight, so that’s the whole source/version + date situation — minimal, mysterious, iconic 💅✨