Initial import of the CDE 2.1.30 sources from the Open Group.
This commit is contained in:
381
cde/doc/C/guides/man/m3_Dt/ActionIn.sgm
Normal file
381
cde/doc/C/guides/man/m3_Dt/ActionIn.sgm
Normal file
@@ -0,0 +1,381 @@
|
||||
<!-- $XConsortium: ActionIn.sgm /main/10 1996/09/08 20:02:14 rws $ -->
|
||||
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
||||
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
||||
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
||||
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
||||
<!-- (c) Copyright 1995 Novell, Inc. -->
|
||||
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
||||
<!-- (c) Copyright 1995 Hitachi. -->
|
||||
<![ %CDE.C.CDE; [<refentry id="CDEMX.XCDI.MAN12.rsml.1">]]><![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN12.rsml.1">]]><refmeta>
|
||||
<refentrytitle>DtActionInvoke</refentrytitle><manvolnum>library call</manvolnum>
|
||||
</refmeta><refnamediv><refname><function>DtActionInvoke</function></refname>
|
||||
<refpurpose>invoke a &str-XZ; action</refpurpose></refnamediv><!-- CDE Common
|
||||
Source Format, Version 1.0.0--><!-- *************************************************************************--><!--
|
||||
** (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company--><!-- ** (c)
|
||||
Copyright 1993, 1994, 1995 International Business Machines Corp.--><!-- **
|
||||
(c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.--><!-- ** (c) Copyright
|
||||
1993, 1994, 1995 Novell, Inc.--><!-- *************************************************************************--><refsynopsisdiv>
|
||||
<funcsynopsis remap="ANSI">
|
||||
<funcsynopsisinfo>#include <Dt/Action.h></funcsynopsisinfo>
|
||||
<funcdef>DtActionInvocationID <function>DtActionInvoke</function></funcdef>
|
||||
<paramdef>Widget <parameter>w</parameter></paramdef>
|
||||
<paramdef>char *<parameter>action</parameter></paramdef>
|
||||
<paramdef>DtActionArg *<parameter>args</parameter></paramdef>
|
||||
<paramdef>int <parameter>argCount</parameter></paramdef>
|
||||
<paramdef>char *<parameter>termOpts</parameter></paramdef>
|
||||
<paramdef>char *<parameter>execHost</parameter></paramdef>
|
||||
<paramdef>char *<parameter>contextDir</parameter></paramdef>
|
||||
<paramdef>int <parameter>useIndicator</parameter></paramdef>
|
||||
<paramdef>DtActionCallbackProc <parameter>statusUpdateCb</parameter></paramdef>
|
||||
<paramdef>XtPointer <parameter>client_data</parameter></paramdef>
|
||||
</funcsynopsis></refsynopsisdiv><refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>The <function>DtActionInvoke</function> function provides a way for
|
||||
applications to invoke desktop actions on file or buffer arguments. Applications
|
||||
can register a callback for receiving action-done status and return arguments.
|
||||
</para>
|
||||
<para>The actions and data types databases must be initialized and loaded
|
||||
(using &cdeman.DtInitialize; and &cdeman.DtDbLoad;)
|
||||
before <function>DtActionInvoke</function> can run successfully.</para>
|
||||
<para>The <symbol role="Variable">w</symbol> 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-<systemitem class="Constant">NULL</systemitem> value.</para>
|
||||
<para>The <symbol role="Variable">action</symbol> 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 <![ %CDE.C.CDE; [ &cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>This
|
||||
argument must have a non-<systemitem class="Constant">NULL</systemitem> value.
|
||||
</para>
|
||||
<para>The <symbol role="Variable">args</symbol> 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 <symbol role="Variable">args</symbol> must be <systemitem class="Constant">NULL</systemitem>. The
|
||||
items in this array are assigned to the option argument keywords referenced
|
||||
in the action definition (see <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>The
|
||||
<symbol role="Variable">n</symbol>th item is assigned to keyword %Arg_ <symbol role="Variable">n</symbol>%. For example, the second item is assigned to %Arg_<emphasis>2</emphasis>%.</para>
|
||||
<para>The <emphasis>argCount</emphasis> argument is the number of action arguments
|
||||
provided in the array <symbol role="Variable">args</symbol> references.</para>
|
||||
<para>The <emphasis>termOpts</emphasis> argument is a string providing special
|
||||
execution information for the terminal emulator used for <systemitem class="Constant">COMMAND</systemitem> actions of <systemitem class="Constant">WINDOW_TYPE</systemitem> <systemitem class="Constant">TERMINAL</systemitem> or <systemitem class="Constant">PERM_TERMINAL</systemitem>. (See <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>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 <systemitem class="Constant">NULL</systemitem>.</para>
|
||||
<para>The <emphasis>execHost</emphasis> argument is a string identifying a
|
||||
preferred execution host for this action. The <emphasis>execHost</emphasis>
|
||||
specified here, supersedes the list of execution hosts defined in the action
|
||||
definition. If <emphasis>execHost</emphasis> is <systemitem class="Constant">NULL</systemitem>, the execution host for the action is obtained from the
|
||||
action definition as described in <![ %CDE.C.CDE; [&cdeman.dtactionfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">. ]]></para>
|
||||
<para>The <emphasis>contextDir</emphasis> 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, <Filename>/usr/tmp</Filename> or <Filename>/net/hostb/tmp</Filename>).
|
||||
This value is only used if the action definition does not explicitly specify
|
||||
a working directory in the <systemitem class="Constant">CWD</systemitem> field
|
||||
of the action definition. If <emphasis>contextDir</emphasis> is <systemitem class="Constant">NULL</systemitem>, the current working directory of the action
|
||||
is obtained from the action definition, as described in <![ %CDE.C.CDE; [ &cdeman.dtactionfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">. ]]></para>
|
||||
<para>If the <emphasis>useIndicator</emphasis> flag is zero, <function>DtActionInvoke</function> does not provide any direct indication to the user that an action
|
||||
has been invoked. If the <emphasis>useIndicator</emphasis> 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).</para>
|
||||
<para>The <emphasis>statusUpdateCb</emphasis> callback may be activated if
|
||||
the invoked actions have returnable status (for example, a <systemitem class="Constant">TT_MSG(TT_REQUEST)</systemitem> returning <systemitem class="Constant">DtACTION_DONE</systemitem> ). At a minimum, a <systemitem class="Constant">DtACTION_INVOKED</systemitem> status is returned when <function>DtActionInvoked</function>
|
||||
has finished processing and has completely invoked any resulting actions,
|
||||
and a <systemitem class="Constant">DtACTION_DONE</systemitem> or equivalent
|
||||
done status is returned when all actions terminate. If <emphasis>statusUpdateCb</emphasis> is set to <systemitem class="Constant">NULL</systemitem>, subsequent
|
||||
action status is not returned. (See &cdeman.Dt.Action.h;
|
||||
for a list of all <structname role="typedef">DtActionStatus</structname> codes,
|
||||
and see &cdeman.DtActionCallbackProc; for details on <emphasis>statusUpdateCb</emphasis> and a list of specific <structname role="typedef">DtActionStatus</structname> codes it can return.)</para>
|
||||
<para>The <symbol role="Variable">client_data</symbol> argument is optional
|
||||
data to be passed to the <emphasis>statusUpdateCb</emphasis> callback when
|
||||
invoked.</para>
|
||||
<para>The <function>DtActionInvoke</function> function searches the action
|
||||
database for an entry that matches the specified action name, and accepts
|
||||
arguments of the class, type and count provided.</para>
|
||||
<para>If <function>DtActionInvoke</function> 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 <structname role="typedef">DtActionArg</structname> structure that may have been modified by the action
|
||||
are returned by the callback if a <emphasis>statusUpdateCb</emphasis> callback
|
||||
is provided. For <structname role="typedef">DtActionBuffer</structname> arguments,
|
||||
the writable flag acts as a hint that the buffer is allowed to be modified
|
||||
and returned.</para>
|
||||
<para>The <structname role="typedef">DtActionBuffer</structname> structure
|
||||
contains at least the following members:</para>
|
||||
<informaltable remap="center" orient="Port">
|
||||
<tgroup cols="3">
|
||||
<colspec align="Left" colname="1">
|
||||
<colspec align="Left" colname="2">
|
||||
<colspec align="Left" colname="3">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><computeroutput>void</computeroutput></entry>
|
||||
<entry><computeroutput>*bp</computeroutput></entry>
|
||||
<entry>location of buffer</entry></row>
|
||||
<row>
|
||||
<entry><computeroutput>int</computeroutput></entry>
|
||||
<entry><computeroutput>size</computeroutput></entry>
|
||||
<entry>size of buffer in bytes</entry></row>
|
||||
<row>
|
||||
<entry><computeroutput>char</computeroutput></entry>
|
||||
<entry><computeroutput>*type</computeroutput></entry>
|
||||
<entry>optional type of buffer</entry></row>
|
||||
<row>
|
||||
<entry><computeroutput>char</computeroutput></entry>
|
||||
<entry><computeroutput>*name</computeroutput></entry>
|
||||
<entry>optional name of buffer</entry></row>
|
||||
<row>
|
||||
<entry><computeroutput>Boolean</computeroutput></entry>
|
||||
<entry><computeroutput>writable</computeroutput></entry>
|
||||
<entry>action is allowed to modify and return the buffer</entry></row></tbody>
|
||||
</tgroup></informaltable>
|
||||
<para>The <structname role="typedef">DtActionFile</structname> structure contains
|
||||
at least the following member:</para>
|
||||
<informaltable remap="center" orient="Port">
|
||||
<tgroup cols="3">
|
||||
<colspec align="Left" colname="1">
|
||||
<colspec align="Left" colname="2">
|
||||
<colspec align="Left" colname="3">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><computeroutput>char</computeroutput></entry>
|
||||
<entry><computeroutput>*name</computeroutput></entry>
|
||||
<entry>name of file</entry></row></tbody></tgroup></informaltable>
|
||||
<para>The <structname role="typedef">DtActionArg</structname> structure contains
|
||||
at least the following members:</para>
|
||||
<informaltable remap="center" orient="Port">
|
||||
<tgroup cols="3">
|
||||
<colspec align="Left" colname="1">
|
||||
<colspec align="Left" colname="2">
|
||||
<colspec align="Left" colname="3">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><computeroutput>int</computeroutput></entry>
|
||||
<entry><computeroutput>argClass</computeroutput></entry>
|
||||
<entry>see argument class types ( <systemitem class="Constant">ARG_CLASS</systemitem>
|
||||
field)</entry></row>
|
||||
<row>
|
||||
<entry><computeroutput>DtActionFile</computeroutput></entry>
|
||||
<entry><computeroutput>u.file</computeroutput></entry>
|
||||
<entry>union to a DtActionFile structure</entry></row>
|
||||
<row>
|
||||
<entry><computeroutput>DtActionBuffer</computeroutput></entry>
|
||||
<entry><computeroutput>u.buffer</computeroutput></entry>
|
||||
<entry>union to a DtActionBuffer structure</entry></row></tbody></tgroup>
|
||||
</informaltable>
|
||||
<para>where <emphasis>argClass</emphasis> is <systemitem class="Constant">DtACTION_FILE</systemitem> or <systemitem class="Constant">DtACTION_BUFFER</systemitem>. The action service may set <emphasis>argClass</emphasis> to <systemitem class="Constant">DtACTION_NULLARG</systemitem> for action arguments returned
|
||||
by a <emphasis>statusUpdateCb</emphasis> to indicate that the argument is
|
||||
not being updated or has been removed. <systemitem class="Constant">DtACTION_NULLARG</systemitem> cannot be present in action arguments passed to <function>DtActionInvoke</function>.</para>
|
||||
<para>The <function>DtActionInvoke</function> function accepts a pointer to
|
||||
an array of <structname role="typedef">DtActionArg</structname> structures
|
||||
describing the objects to be provided as arguments to the action. The
|
||||
<symbol role="Variable">args</symbol> structure can be modified or freed after <function>DtActionInvoke</function> returns.</para>
|
||||
<para>A single call to <function>DtActionInvoke</function> 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 <structname role="typedef">DtActionInvocationID</structname> may represent a group of running actions, and subsequent execution
|
||||
management services <![ %CDE.C.CDE; [(DtAction) ]]>calls operate on that group
|
||||
of actions.</para>
|
||||
<para>For <systemitem class="Constant">DtACTION_BUFFER</systemitem> arguments,
|
||||
the action service first tries to type the buffer <emphasis>*bp</emphasis>
|
||||
using the <symbol role="Variable">name</symbol> field (see <![ %CDE.C.CDE; [ &cdeman.dtdtsfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.DATAT.anch.3" Role="2">). ]]>The
|
||||
<symbol role="Variable">name</symbol> field would typically contain a value resembling
|
||||
a file name with an optional extension describing its type. If the
|
||||
<symbol role="Variable">name</symbol> field is <systemitem class="Constant">NULL</systemitem>,
|
||||
then the action service uses the type specified in the <symbol role="Variable">type</symbol> field. If the <symbol role="Variable">type</symbol> field is <systemitem class="Constant">NULL</systemitem>, then the action service types the buffer <emphasis>*bp</emphasis> by content (see <![ %CDE.C.CDE; [&cdeman.dtdtsfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.DATAT.anch.3" Role="2">). ]]>If
|
||||
the <symbol role="Variable">name</symbol> and <symbol role="Variable">type</symbol>
|
||||
fields are both non-<systemitem class="Constant">NULL</systemitem>,
|
||||
then the action service uses the <symbol role="Variable">name</symbol> field
|
||||
for typing and ignores the <symbol role="Variable">type</symbol> field. If
|
||||
the buffer pointer <emphasis>bp</emphasis> is <systemitem class="Constant">NULL</systemitem> or <symbol role="Variable">size</symbol> is equal to zero,
|
||||
a buffer with no contents is used in the resulting action. If returned, the
|
||||
buffer pointer <emphasis>bp</emphasis> is defined, and <symbol role="Variable">size</symbol> is equal to or greater than zero.</para>
|
||||
<para>When necessary, <systemitem class="Constant">DtACTION_BUFFER</systemitem>
|
||||
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-<systemitem class="Constant">NULL</systemitem> <symbol role="Variable">name</symbol> field is given, it is
|
||||
used in the construction of the temporary file name (for example, <Filename>/myhome/.dt/tmp/name</Filename>). If the use of <symbol role="Variable">name</symbol>
|
||||
would cause a conflict with an existing file, or <symbol role="Variable">name</symbol> is <systemitem class="Constant">NULL</systemitem>, the action
|
||||
service generates a temporary file name. The permission bits on the temporary
|
||||
file are set according to the <emphasis>writable</emphasis> field and the <systemitem class="Constant">IS_EXECUTABLE</systemitem> attribute from the action service
|
||||
associated with the <symbol role="Variable">type</symbol> field.</para>
|
||||
<para>For <systemitem class="Constant">DtACTION_FILE</systemitem> arguments,
|
||||
<symbol role="Variable">name</symbol> is required.</para>
|
||||
<para>For <systemitem class="Constant">DtACTION_BUFFER</systemitem> arguments,
|
||||
<symbol role="Variable">name</symbol> cannot contain slash characters.</para>
|
||||
<para>Errors encountered are either displayed to the user in a dialog box
|
||||
or reported in the desktop errorlog file (<Filename>$HOME/.dt/errorlog</Filename>,
|
||||
unless configured otherwise).</para>
|
||||
</refsect1><refsect1><?Pub Caret1>
|
||||
<title>RESOURCES</title>
|
||||
<para>This section describes the X11 resources the <function>DtActionInvoke</function> 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 <literal>*resourceName: value</literal>. <![ %CDE.C.CDE; [For
|
||||
example, to set the terminal emulator to <command>xterm</command>(1) for all
|
||||
clients, the application can use <literal>*localTerminal: xterm</literal>.
|
||||
The resources can also be defined on a per client basis. For example, it can
|
||||
use <literal>Dtfile*localTerminal: xterm</literal> to set the terminal emulator
|
||||
to <command>xterm</command>(1) for the <command>dtfile</command> client only.
|
||||
(See <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>]]></para>
|
||||
<informaltable remap="center" orient="port">
|
||||
<tgroup cols="4" colsep="0" rowsep="0">
|
||||
<colspec align="left" colwidth="155*">
|
||||
<colspec align="left" colwidth="147*">
|
||||
<colspec align="left" colwidth="74*">
|
||||
<colspec align="left" colwidth="81*">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry></entry>
|
||||
<entry align="center" valign="top"><literal>X11 Resources</literal></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry align="left" valign="top"><literal>Name</literal></entry>
|
||||
<entry align="left" valign="top"><literal>Class</literal></entry>
|
||||
<entry align="left" valign="top"><literal>Value Type</literal></entry>
|
||||
<entry align="left" valign="top"><literal>Default</literal></entry></row>
|
||||
<row>
|
||||
<entry align="left" valign="top"><literal>localterminal</literal></entry>
|
||||
<entry align="left" valign="top"><literal>LocalTerminal</literal></entry>
|
||||
<entry align="left" valign="top"><literal>string</literal></entry>
|
||||
<entry align="left" valign="top">``Dtterm''</entry></row>
|
||||
<row>
|
||||
<entry align="left" valign="top"><literal>remoteTerminals</literal></entry>
|
||||
<entry align="left" valign="top"><literal>RemoteTerminals</literal></entry>
|
||||
<entry align="left" valign="top"><literal>string</literal></entry>
|
||||
<entry align="left" valign="top">``Dtterm''</entry></row>
|
||||
<row>
|
||||
<entry align="left" valign="top"><literal>waitTime</literal></entry>
|
||||
<entry align="left" valign="top"><literal>WaitTime</literal></entry>
|
||||
<entry align="left" valign="top"><literal>number</literal></entry>
|
||||
<entry align="left" valign="top">3</entry></row></tbody></tgroup></informaltable>
|
||||
<variablelist>
|
||||
<varlistentry><term><literal>LocalTerminal</literal></term>
|
||||
<listitem>
|
||||
<para>Defines an alternative local terminal emulator for Command actions of <systemitem class="Constant">WINDOW_TYPE</systemitem> <systemitem class="Constant">TERMINAL</systemitem> or <systemitem class="Constant">PERM_TERMINAL</systemitem> to
|
||||
use. The default terminal emulator is &cdeman.dtterm;.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>RemoteTerminals</literal></term>
|
||||
<listitem>
|
||||
<para>Defines a comma-separated list of host and terminal emulator pairs.
|
||||
When a remote <systemitem class="Constant">COMMAND</systemitem> 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 <literal>−e</literal> argument. (Thus, if another
|
||||
terminal emulator than <command>dtterm</command> is used, it must support
|
||||
the <literal>−e</literal> argument. <![ %CDE.C.CDE; [See <command>xterm</command>(1). ]]></para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>WaitTime</literal></term>
|
||||
<listitem>
|
||||
<para>Used to assign an alternative integer value, in seconds, to the threshold
|
||||
successful return time interval. If a <systemitem class="Constant">COMMAND</systemitem> action of <systemitem class="Constant">WINDOW_TYPE</systemitem> <systemitem class="Constant">TERMINAL</systemitem> 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 <systemitem class="Constant">TERMINAL</systemitem> window command exits before <literal>WaitTime</literal> seconds have elapsed, the terminal emulator window is forced
|
||||
to remain open, as if it were of <systemitem class="Constant">TYPE</systemitem> <systemitem class="Constant">PERM_TERMINAL</systemitem>. The default value of <literal>WaitTime</literal> is 3 seconds.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1><refsect1>
|
||||
<title>RETURN VALUE</title>
|
||||
<para>Upon successful completion, the <function>DtActionInvoke</function>
|
||||
function returns a <structname role="typedef">DtActionInvocationID</structname>.
|
||||
The ID can be used in subsequent execution management services <![ %CDE.C.CDE; [(DtAction) ]]>calls
|
||||
to manipulate the actions while they are running. <structname role="typedef">DtActionInvocationID</structname>s are only recycled after many have been
|
||||
generated.</para>
|
||||
</refsect1><refsect1>
|
||||
<title>APPLICATION USAGE</title>
|
||||
<para>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 <function>DtActionInvoke</function> returns.</para>
|
||||
<para>Since <function>DtActionInvoke</function> spawns subprocesses to start
|
||||
local actions, the caller should use <function>waitpid</function>(2) instead
|
||||
of <function>wait</function>(2) to distinguish between processes started by
|
||||
the action service and those the caller starts.</para>
|
||||
</refsect1><refsect1>
|
||||
<title>EXAMPLES</title>
|
||||
<para>Given the following action definition:</para>
|
||||
<informalexample remap="indent">
|
||||
<programlisting>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.
|
||||
}</programlisting>
|
||||
</informalexample>
|
||||
<para>The following call invokes the action
|
||||
<symbol role="Message">Edit</symbol> on the arguments
|
||||
<emphasis>aap</emphasis> supplies:</para>
|
||||
<informalexample remap="indent">
|
||||
<programlisting> DtActionInvoke(w, "Edit", aap, 3, NULL, NULL, NULL, 1,
|
||||
myCallback, myClientData);</programlisting>
|
||||
</informalexample>
|
||||
<para>The working directory for the action defaults to the current working
|
||||
directory.
|
||||
The execution host is the default execution host.</para>
|
||||
<para>If the variable
|
||||
<emphasis>aap</emphasis> points to an array of
|
||||
<literal>ActionArg</literal> data structures
|
||||
containing the following information:</para>
|
||||
<informalexample remap="indent">
|
||||
<programlisting>{
|
||||
argClass = DtACTION_FILE;
|
||||
struct {
|
||||
name="/myhome/file1.txt";
|
||||
} file;
|
||||
}</programlisting>
|
||||
</informalexample>
|
||||
<informalexample remap="indent">
|
||||
<programlisting>{
|
||||
argClass = DtACTION_FILE;
|
||||
struct {
|
||||
name="file2.txt";
|
||||
} file;
|
||||
}</programlisting>
|
||||
</informalexample>
|
||||
<informalexample remap="indent">
|
||||
<programlisting>{
|
||||
argClass = DtACTION_BUFFER;
|
||||
struct {
|
||||
bp=(void *) myEditBuffer;
|
||||
size=lengthOfMyEditBuffer;
|
||||
type=NULL;
|
||||
name="Doc1.txt"
|
||||
writable=TRUE;
|
||||
} buffer;
|
||||
}</programlisting>
|
||||
</informalexample>
|
||||
<para>and the current working directory is
|
||||
<Filename>/cwd</Filename>, then the
|
||||
<symbol role="Message">Edit</symbol> action results in the execution string:
|
||||
</para>
|
||||
<informalexample remap="indent">
|
||||
<programlisting>textedit /myhome/file1.txt /cwd/file2.txt /myhome/.dt/tmp/Doc1.txt
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
<para>When the action completes,
|
||||
<emphasis>myCallback</emphasis> is called and
|
||||
the callback returns the buffer argument.</para>
|
||||
</refsect1><refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>&cdeman.Dt.Action.h;, <![ %CDE.C.CDE; [ <command>xterm</command>(1), <function>XtFree</function>(3), <function>XtMalloc</function>(3), ]]><![ %CDE.C.XO; [<Function>XtFree</Function>(3), <Function>XtMalloc</Function>(3) in the &str-Zt;;
|
||||
]]>&cdeman.DtDbLoad;, &cdeman.DtInitialize;, &cdeman.DtActionCallbackProc;, <![ %CDE.C.CDE; [&cdeman.dtactionfile;, &cdeman.dtdtfile;, &cdeman.dtdtsfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">, <XRef Linkend="XCDI.M4DTS.anch.1" Role="3">, <XRef Linkend="XCDI.DATAT.anch.3" Role="2">. ]]></para>
|
||||
</refsect1></refentry>
|
||||
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
|
||||
<?Pub *0000053895>
|
||||
Reference in New Issue
Block a user