DtActionInvokeOnFiles(3) — Subroutines

NAME

DtActionInvokeOnFiles(3) — the API for invoking a CDE action with file arguments.

SYNOPSIS

#include <X11/Intrinsic.h>
#include <Dt/Action.h>
void DtActionInvokeOnFiles (

Widgetw,
char∗actionName,
intargCount,
fileArgpargs,
char∗termOpts,
char∗execHost,
char∗contextHost,
char∗contextDir,
intuseIndicator)

DESCRIPTION

DtActionInvokeOnFiles provides a way to invoke desktop actions on arguments which represent files.

The actions and datatypes databases must have been initialized and loaded (using DtInitialize(3) and DtDbLoad(3) before DtActionInvokeOnFiles can run successfully. A number of action-instance-specific parameters are provided which allow modification of the Action’s behavior.

wa Widget which will become the parent of any dialogs or error messages which may result from the action invocation. This widget should be a toplevel application shell widget which will continue to exist for the expected lifetime of the action. This parameter must have a non-NULL value.

actionName
The name of the action which is to be invoked. There may be more than one action with the same name. The action selected for a particular invocation depends on the type and number of arguments provided. This parameter must have a non-NULL value.

argCount
The number of arguments provided in the array referenced by args.

argsAn array of fileArg structures containing information about the arguments for this action invocation. If there are no arguments then the value of fileArgs may be NULL.

termOpts
A (optional) string providing special execution information for the terminal emulator used for Command actions of Window Type: TERMINAL or PERM_TERMINAL. If this string contains embedded blanks then it must be quoted. This string is typically used to pass on title, geometry, color, font, etc. information to the terminal emulator. It must be in a form recognizable by the expected terminal emulator. This parameter may be NULL.

execHost
An (optional) string identifying a preferred execution host for this action. The execHost specified here will be placed at the head of the list of execution hosts defined in the action definition. This parameter will generally be a NULL pointer.

contextHost
An (optional) string identifying a default host in whose context file names are to be interpreted. This value is only used if the action definition does not explicitly specify a hostname in the CWD field of the action definition. This parameter will generally be a NULL pointer.

contextDir
An (optional) string identifying a default working directory for the action. File name arguments are interpreted relative to this directory. This value is only used if the action definition does not explicitly specify a working directory in the CWD field of the action definition. This parameter will generally be a NULL pointer.

useIndicator
If useIndicator is non-zero then the activity indicator light on the front panel will be made to flash in conjunction with this action.

DtActionInvokeOnFiles searches the action database for an entry which matches the specified action name, and accepts files of the, type and number provided. If a matching action is found, then information from that action will be used as a pattern for construction the final execution string or message. The supplied objects will be inserted into the indicated positions within the execution string or message. If any required parameters are missing, then the user will be prompted to supply them, by means of a dialog box.

typedef struct {   /∗ file argument info ∗/
            char    ∗name; /∗ ...file name ([host:]/path/basename format) ∗/
            char    ∗type; /∗ ... (opt.) file type string ∗/
            char    ∗host; /∗ ... (opt.) the host on which to interpret the
                               file path name ∗/
} fileArg, ∗fileArgp;

Optional pointers may be NULL. For FILE objects, name is required; this is the name of the file being referenced. The type string is optional, if a non-NULL value is provided, it is used as the type of the file; otherwise the type of the file is determined using the datatypes database. The host field is optional; if a non-NULL value is provided, the file name will be interpreted relative to this host; otherwise it will be interpreted relative to the context host for the action.

DtActionInvokeOnFiles accepts a pointer to an array of fileArg structures in the args parameter. It is up to the caller to allocate space for this array. The caller may free this space after DtActionInvokeOnFiles returns.

X11 RESOURCES

This section describes the X11 resources recognized by the Action Library and its subcomponents. In general the resource class string always begins with an upper case letter. The corresponding resource name sting 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" for all clients, use "∗localTerminal: xterm". The resources can also be defined on a per client basis. For example, use "Dtfile∗localTerminal: xterm" to set the terminal emulator to "xterm" for the "dtfile" client only.

The following X11 resources are recognized:

• LocalTerminal — specifies an alternate local terminal emulator

• RemoteTerminal — specifies a comma-separated list of host/terminal emulator pairs.

• AutoXhosting — turns the autoXhosting feature on or off.

• WaitTime — defines a threshold time interval for "successful" command completion.

The LocalTerminal resource defines an alternate local terminal emulator to be used by Command actions of Window Type TERMINAL or PERM_TERMINAL. The default terminal emulator is: "dtterm".

The RemoteTerminal resource defines a comma-separated list of "host: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 will be used for that command. All specified terminal emulators must recognize the "-e" parameter. (see xterm(1)). The default is to use localTerminal.

The AutoXhosting resource can be used to turn the "automatic Xhosting" feature on or off. In situations where remote clients are required to open windows on the local display, they must be granted display access. This can be done by providing the remote client access to the key for this display (via xauth(1x)) or by granting blanket access to the remote system via xhost(1x). If the autoXhosting resource value is "True" then blanket access is automatically granted to a given remote system, using xhost, whenever a remote action to that system is invoked. The default value for this resource is: "False".

The WaitTime resource can be 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; then the terminal emulator may be unmapped before the user has a chance to read the stderr from the failed command. This resource provides a workaround to this problem. If a TERMINAL window command exits before WaitTime seconds have elapsed then 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 VALUES

The DtActionInvokeOnFiles function does not return a value. Actions are invoked on a "fire and forget basis".

ERRORS

This function does not return error codes, however the user will be notified of severe errors interactively via error dialogs. Low level errors (e.g. errors encountered reading the action database) will be reported in the desktop errorlog file (usually in $HOME/.dt/errorlog).

EXAMPLES

Given the following action definition:

ACTION Edit
{
LABEL"Text Edit Action"
TYPECOMMAND
WINDOW_TYPE TERMINAL
EXEC_STRING"textedit %Args%"
DESCRIPTIONThis action will invoke the "edit" command on an
arbitrary number of arguments. A terminal emulator
will be provided for this action’s I/O. EXEC_HOST and
CWD are not specified so the defaults will be used
for both quantities.
}

The following invocation:

DtActionInvokeOnFiles(w,"Edit",1,aap,NULL,NULL,NULL,NULL,1);

will invoke the action "Edit", on the argument supplied by aap. The working directory for the action, will default to the current working directory; The execution host will be the default execution host

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

     {
            name="/myhome/file1";
            type="TEXT";
            host="remotehost";
    }/∗ file argument #1 ∗/
     {
            name="file2";
            type=NULL
            host=NULL;
    } /∗ file argument #2 ∗/

and assuming the "remotehost" filesystem is mounted at "/nfs/remotehost", then the "Edit" action will result in the execution string:

textedit /nfs/remotehost/myhome/file1 file2

Museum

Related Articles