Партнёры:
Хостинг:
NAME
DtActionInvoke - invoke a CDE 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
The DtActionInvoke() function provides a way for applica-
tions to invoke desktop actions on file or buffer arguments.
Applications can register a callback for receiving action-
done status and return arguments.
The actions and data types databases must be initialized and
loaded (using DtInitialize(3) and DtDbLoad(3)) before DtAc-
tionInvoke() can run successfully.
The w argument is a widget that becomes the parent of any
dialogs or error messages resulting from action invocation.
This widget 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.
The action argument is 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.
The args argument is 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%.
The argCount argument is the number of action arguments pro-
vided in the array args references.
The termOpts argument is a string providing special execu-
tion 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 termi-
nal emulator. This information must be in a form the
expected terminal emulator recognizes. This argument can be
NULL.
The execHost argument is 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).
The contextDir argument is 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 dtac-
tionfile(4).
If the useIndicator flag is zero, DtActionInvoke() does not
provide any direct indication to the user that an action has
been invoked. If the useIndicator flag 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).
The statusUpdateCb callback 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 statusUp-
dateCb is set to NULL, subsequent action status is not
returned. (See <DtAction.h> for a list of all DtAction-
Status codes, and see DtActionCallbackProc(3) for details on
statusUpdateCb and a list of specific DtActionStatus codes
it can return.)
The client_data argument is 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.
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 struc-
ture
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 pro-
vided as arguments to the action. The args structure can be
modified or freed after DtActionInvoke() returns.
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 sin-
gle returned DtActionInvocationID may represent a group of
running actions, and subsequent execution management ser-
vices (DtAction) calls operate on that group of actions.
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 invoca-
tion, and reconverted back to buffers after action termina-
tion (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 tem-
porary 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).
RESOURCES
This section describes the X11 resources the
DtActionInvoke() function 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 emu-
lator to xterm(1X) 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(1X) for the dtfile client only. (See dtaction-
file(4)).
X11 Resources
_______________|_________________|____________|__________________
Name | Class | Value Type| Default
_______________|_________________|____________|__________________
localterminal | LocalTerminal | string | ``Dtterm''
remoteTerminals| RemoteTerminals| string | ``Dtterm''
waitTime | WaitTime | number | 3
LocalTerminal
Defines an alternative local terminal emulator for
Command actions of WINDOW_TYPE TERMINAL or
PERM_TERMINAL to use. The default terminal emula-
tor is dtterm(1).
RemoteTerminals
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 ter-
minal emulator associated with that host is used
for that command. The list is passed to the termi-
nal emulator using the -e argument. (Thus, if
another terminal emulator than dtterm is used, it
must support the -e argument. See xterm(1X).
WaitTime
Used to assign an alternative integer value, in
seconds, to the threshold successful return time
interval. If a COMMAND action of WINDOW_TYPE TER-
MINAL fails, the terminal emulator may be unmapped
before the user has a chance to read the standard
error from the failed command. This resource pro-
vides 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 sub-
sequent execution management services (DtAction) calls to
manipulate the actions while they are running. DtActionIn-
vocationIDs are only recycled after many have been gen-
erated.
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 DtActionIn-
voke() 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 ser-
vice 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 execu-
tion 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
DtAction(5), xterm(1X), XtFree(3X), XtMalloc(3X),
DtDbLoad(3), DtInitialize(3), DtActionCallbackProc(3), dtac-
tionfile(4), dtdtfile(4), dtdtsfile(4).
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |