ActionIn.sgm 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
  1. <!-- $XConsortium: ActionIn.sgm /main/10 1996/09/08 20:02:14 rws $ -->
  2. <!-- (c) Copyright 1995 Digital Equipment Corporation. -->
  3. <!-- (c) Copyright 1995 Hewlett-Packard Company. -->
  4. <!-- (c) Copyright 1995 International Business Machines Corp. -->
  5. <!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
  6. <!-- (c) Copyright 1995 Novell, Inc. -->
  7. <!-- (c) Copyright 1995 FUJITSU LIMITED. -->
  8. <!-- (c) Copyright 1995 Hitachi. -->
  9. <![ %CDE.C.CDE; [<refentry id="CDEMX.XCDI.MAN12.rsml.1">]]><![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN12.rsml.1">]]><refmeta>
  10. <refentrytitle>DtActionInvoke</refentrytitle><manvolnum>library call</manvolnum>
  11. </refmeta><refnamediv><refname><function>DtActionInvoke</function></refname>
  12. <refpurpose>invoke a &str-XZ; action</refpurpose></refnamediv><!-- CDE Common
  13. Source Format, Version 1.0.0--><!-- *************************************************************************--><!--
  14. ** (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company--><!-- ** (c)
  15. Copyright 1993, 1994, 1995 International Business Machines Corp.--><!-- **
  16. (c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.--><!-- ** (c) Copyright
  17. 1993, 1994, 1995 Novell, Inc.--><!-- *************************************************************************--><refsynopsisdiv>
  18. <funcsynopsis remap="ANSI">
  19. <funcsynopsisinfo>#include &lt;Dt/Action.h></funcsynopsisinfo>
  20. <funcdef>DtActionInvocationID <function>DtActionInvoke</function></funcdef>
  21. <paramdef>Widget <parameter>w</parameter></paramdef>
  22. <paramdef>char *<parameter>action</parameter></paramdef>
  23. <paramdef>DtActionArg *<parameter>args</parameter></paramdef>
  24. <paramdef>int <parameter>argCount</parameter></paramdef>
  25. <paramdef>char *<parameter>termOpts</parameter></paramdef>
  26. <paramdef>char *<parameter>execHost</parameter></paramdef>
  27. <paramdef>char *<parameter>contextDir</parameter></paramdef>
  28. <paramdef>int <parameter>useIndicator</parameter></paramdef>
  29. <paramdef>DtActionCallbackProc <parameter>statusUpdateCb</parameter></paramdef>
  30. <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
  31. </funcsynopsis></refsynopsisdiv><refsect1>
  32. <title>DESCRIPTION</title>
  33. <para>The <function>DtActionInvoke</function> function provides a way for
  34. applications to invoke desktop actions on file or buffer arguments. Applications
  35. can register a callback for receiving action-done status and return arguments.
  36. </para>
  37. <para>The actions and data types databases must be initialized and loaded
  38. (using &cdeman.DtInitialize; and &cdeman.DtDbLoad;)
  39. before <function>DtActionInvoke</function> can run successfully.</para>
  40. <para>The <symbol role="Variable">w</symbol> argument is a widget that becomes
  41. the parent of any dialogs or error messages resulting from action invocation.
  42. This widget should be a top-level application shell widget that continues
  43. to exist for the action's expected lifetime. This argument must have a non-<systemitem class="Constant">NULL</systemitem> value.</para>
  44. <para>The <symbol role="Variable">action</symbol> argument is the name of
  45. the action to be invoked. The action database may define more than one action
  46. with the same name. The action selected for a particular invocation depends
  47. 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
  48. argument must have a non-<systemitem class="Constant">NULL</systemitem> value.
  49. </para>
  50. <para>The <symbol role="Variable">args</symbol> argument is an array of action
  51. argument structures containing information about the arguments for this action
  52. invocation. If there are no arguments, the value of <symbol role="Variable">args</symbol> must be <systemitem class="Constant">NULL</systemitem>. The
  53. items in this array are assigned to the option argument keywords referenced
  54. in the action definition (see <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>The
  55. <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>
  56. <para>The <emphasis>argCount</emphasis> argument is the number of action arguments
  57. provided in the array <symbol role="Variable">args</symbol> references.</para>
  58. <para>The <emphasis>termOpts</emphasis> argument is a string providing special
  59. 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
  60. string must be quoted if it contains embedded blanks. The application uses
  61. this string to pass on title, geometry, color and font information to the
  62. terminal emulator. This information must be in a form the expected terminal
  63. emulator recognizes. This argument can be <systemitem class="Constant">NULL</systemitem>.</para>
  64. <para>The <emphasis>execHost</emphasis> argument is a string identifying a
  65. preferred execution host for this action. The <emphasis>execHost</emphasis>
  66. specified here, supersedes the list of execution hosts defined in the action
  67. definition. If <emphasis>execHost</emphasis> is <systemitem class="Constant">NULL</systemitem>, the execution host for the action is obtained from the
  68. action definition as described in <![ %CDE.C.CDE; [&cdeman.dtactionfile;. ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">. ]]></para>
  69. <para>The <emphasis>contextDir</emphasis> argument is a string identifying
  70. a fallback working directory for the action. File name arguments are interpreted
  71. relative to this directory, which must reside in the local file name space
  72. (for example, <Filename>/usr/tmp</Filename> or <Filename>/net/hostb/tmp</Filename>).
  73. This value is only used if the action definition does not explicitly specify
  74. a working directory in the <systemitem class="Constant">CWD</systemitem> field
  75. of the action definition. If <emphasis>contextDir</emphasis> is <systemitem class="Constant">NULL</systemitem>, the current working directory of the action
  76. 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>
  77. <para>If the <emphasis>useIndicator</emphasis> flag is zero, <function>DtActionInvoke</function> does not provide any direct indication to the user that an action
  78. has been invoked. If the <emphasis>useIndicator</emphasis> flag is non-zero,
  79. the user is notified via some activity indicator (for example, a flashing
  80. light in the front panel) that an action has been invoked. This indication
  81. persists only until the invocation of the action completes (in other words,
  82. until the action begins running).</para>
  83. <para>The <emphasis>statusUpdateCb</emphasis> callback may be activated if
  84. 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>
  85. has finished processing and has completely invoked any resulting actions,
  86. and a <systemitem class="Constant">DtACTION_DONE</systemitem> or equivalent
  87. done status is returned when all actions terminate. If <emphasis>statusUpdateCb</emphasis> is set to <systemitem class="Constant">NULL</systemitem>, subsequent
  88. action status is not returned. (See &cdeman.Dt.Action.h;
  89. for a list of all <structname role="typedef">DtActionStatus</structname> codes,
  90. 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>
  91. <para>The <symbol role="Variable">client_data</symbol> argument is optional
  92. data to be passed to the <emphasis>statusUpdateCb</emphasis> callback when
  93. invoked.</para>
  94. <para>The <function>DtActionInvoke</function> function searches the action
  95. database for an entry that matches the specified action name, and accepts
  96. arguments of the class, type and count provided.</para>
  97. <para>If <function>DtActionInvoke</function> finds a matching action, the
  98. supplied arguments are inserted into the indicated action fields. If any missing
  99. action arguments have an associated prompt string, then a dialog box prompts
  100. the user to supply the arguments; otherwise, missing arguments are ignored.
  101. If too many arguments are supplied to an action requiring more than a single
  102. argument, a warning dialog is posted, allowing the action to be cancelled
  103. or continued, ignoring the extra arguments. If too many arguments are supplied
  104. to an action requiring zero or one arguments, then that action is invoked
  105. once for each of the supplied arguments. Arguments in the <structname role="typedef">DtActionArg</structname> structure that may have been modified by the action
  106. are returned by the callback if a <emphasis>statusUpdateCb</emphasis> callback
  107. is provided. For <structname role="typedef">DtActionBuffer</structname> arguments,
  108. the writable flag acts as a hint that the buffer is allowed to be modified
  109. and returned.</para>
  110. <para>The <structname role="typedef">DtActionBuffer</structname> structure
  111. contains at least the following members:</para>
  112. <informaltable remap="center" orient="Port">
  113. <tgroup cols="3">
  114. <colspec align="Left" colname="1">
  115. <colspec align="Left" colname="2">
  116. <colspec align="Left" colname="3">
  117. <tbody>
  118. <row>
  119. <entry><computeroutput>void</computeroutput></entry>
  120. <entry><computeroutput>*bp</computeroutput></entry>
  121. <entry>location of buffer</entry></row>
  122. <row>
  123. <entry><computeroutput>int</computeroutput></entry>
  124. <entry><computeroutput>size</computeroutput></entry>
  125. <entry>size of buffer in bytes</entry></row>
  126. <row>
  127. <entry><computeroutput>char</computeroutput></entry>
  128. <entry><computeroutput>*type</computeroutput></entry>
  129. <entry>optional type of buffer</entry></row>
  130. <row>
  131. <entry><computeroutput>char</computeroutput></entry>
  132. <entry><computeroutput>*name</computeroutput></entry>
  133. <entry>optional name of buffer</entry></row>
  134. <row>
  135. <entry><computeroutput>Boolean</computeroutput></entry>
  136. <entry><computeroutput>writable</computeroutput></entry>
  137. <entry>action is allowed to modify and return the buffer</entry></row></tbody>
  138. </tgroup></informaltable>
  139. <para>The <structname role="typedef">DtActionFile</structname> structure contains
  140. at least the following member:</para>
  141. <informaltable remap="center" orient="Port">
  142. <tgroup cols="3">
  143. <colspec align="Left" colname="1">
  144. <colspec align="Left" colname="2">
  145. <colspec align="Left" colname="3">
  146. <tbody>
  147. <row>
  148. <entry><computeroutput>char</computeroutput></entry>
  149. <entry><computeroutput>*name</computeroutput></entry>
  150. <entry>name of file</entry></row></tbody></tgroup></informaltable>
  151. <para>The <structname role="typedef">DtActionArg</structname> structure contains
  152. at least the following members:</para>
  153. <informaltable remap="center" orient="Port">
  154. <tgroup cols="3">
  155. <colspec align="Left" colname="1">
  156. <colspec align="Left" colname="2">
  157. <colspec align="Left" colname="3">
  158. <tbody>
  159. <row>
  160. <entry><computeroutput>int</computeroutput></entry>
  161. <entry><computeroutput>argClass</computeroutput></entry>
  162. <entry>see argument class types ( <systemitem class="Constant">ARG_CLASS</systemitem>
  163. field)</entry></row>
  164. <row>
  165. <entry><computeroutput>DtActionFile</computeroutput></entry>
  166. <entry><computeroutput>u.file</computeroutput></entry>
  167. <entry>union to a DtActionFile structure</entry></row>
  168. <row>
  169. <entry><computeroutput>DtActionBuffer</computeroutput></entry>
  170. <entry><computeroutput>u.buffer</computeroutput></entry>
  171. <entry>union to a DtActionBuffer structure</entry></row></tbody></tgroup>
  172. </informaltable>
  173. <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
  174. by a <emphasis>statusUpdateCb</emphasis> to indicate that the argument is
  175. 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>
  176. <para>The <function>DtActionInvoke</function> function accepts a pointer to
  177. an array of <structname role="typedef">DtActionArg</structname> structures
  178. describing the objects to be provided as arguments to the action. The
  179. <symbol role="Variable">args</symbol> structure can be modified or freed after <function>DtActionInvoke</function> returns.</para>
  180. <para>A single call to <function>DtActionInvoke</function> may initiate several
  181. actions or messages. For example, if an action is given three files, but only
  182. needs one, three instances of the action are started, one for each file. As
  183. a result, a single returned <structname role="typedef">DtActionInvocationID</structname> may represent a group of running actions, and subsequent execution
  184. management services <![ %CDE.C.CDE; [(DtAction) ]]>calls operate on that group
  185. of actions.</para>
  186. <para>For <systemitem class="Constant">DtACTION_BUFFER</systemitem> arguments,
  187. the action service first tries to type the buffer <emphasis>*bp</emphasis>
  188. 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
  189. <symbol role="Variable">name</symbol> field would typically contain a value resembling
  190. a file name with an optional extension describing its type. If the
  191. <symbol role="Variable">name</symbol> field is <systemitem class="Constant">NULL</systemitem>,
  192. 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
  193. the <symbol role="Variable">name</symbol> and <symbol role="Variable">type</symbol>
  194. fields are both non-<systemitem class="Constant">NULL</systemitem>,
  195. then the action service uses the <symbol role="Variable">name</symbol> field
  196. for typing and ignores the <symbol role="Variable">type</symbol> field. If
  197. the buffer pointer <emphasis>bp</emphasis> is <systemitem class="Constant">NULL</systemitem> or <symbol role="Variable">size</symbol> is equal to zero,
  198. a buffer with no contents is used in the resulting action. If returned, the
  199. buffer pointer <emphasis>bp</emphasis> is defined, and <symbol role="Variable">size</symbol> is equal to or greater than zero.</para>
  200. <para>When necessary, <systemitem class="Constant">DtACTION_BUFFER</systemitem>
  201. arguments are automatically converted to temporary files prior to actual action
  202. invocation, and reconverted back to buffers after action termination (this
  203. is transparent to the caller). If a non-<systemitem class="Constant">NULL</systemitem> <symbol role="Variable">name</symbol> field is given, it is
  204. 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>
  205. would cause a conflict with an existing file, or <symbol role="Variable">name</symbol> is <systemitem class="Constant">NULL</systemitem>, the action
  206. service generates a temporary file name. The permission bits on the temporary
  207. file are set according to the <emphasis>writable</emphasis> field and the <systemitem class="Constant">IS_EXECUTABLE</systemitem> attribute from the action service
  208. associated with the <symbol role="Variable">type</symbol> field.</para>
  209. <para>For <systemitem class="Constant">DtACTION_FILE</systemitem> arguments,
  210. <symbol role="Variable">name</symbol> is required.</para>
  211. <para>For <systemitem class="Constant">DtACTION_BUFFER</systemitem> arguments,
  212. <symbol role="Variable">name</symbol> cannot contain slash characters.</para>
  213. <para>Errors encountered are either displayed to the user in a dialog box
  214. or reported in the desktop errorlog file (<Filename>$HOME/.dt/errorlog</Filename>,
  215. unless configured otherwise).</para>
  216. </refsect1><refsect1><?Pub Caret1>
  217. <title>RESOURCES</title>
  218. <para>This section describes the X11 resources the <function>DtActionInvoke</function> function recognizes. The resource class string always begins with
  219. an upper-case letter. The corresponding resource name string begins with the
  220. lower case of the same letter. These resources can be defined for all clients
  221. using the Action Library API by specifying <literal>*resourceName: value</literal>. <![ %CDE.C.CDE; [For
  222. example, to set the terminal emulator to <command>xterm</command>(1) for all
  223. clients, the application can use <literal>*localTerminal: xterm</literal>.
  224. The resources can also be defined on a per client basis. For example, it can
  225. use <literal>Dtfile*localTerminal: xterm</literal> to set the terminal emulator
  226. to <command>xterm</command>(1) for the <command>dtfile</command> client only.
  227. (See <![ %CDE.C.CDE; [&cdeman.dtactionfile;). ]]><![ %CDE.C.XO; [<XRef Linkend="XCDI.ACTI.anch.3" Role="2">). ]]>]]></para>
  228. <informaltable remap="center" orient="port">
  229. <tgroup cols="4" colsep="0" rowsep="0">
  230. <colspec align="left" colwidth="155*">
  231. <colspec align="left" colwidth="147*">
  232. <colspec align="left" colwidth="74*">
  233. <colspec align="left" colwidth="81*">
  234. <tbody>
  235. <row>
  236. <entry></entry>
  237. <entry align="center" valign="top"><literal>X11 Resources</literal></entry>
  238. </row>
  239. <row>
  240. <entry align="left" valign="top"><literal>Name</literal></entry>
  241. <entry align="left" valign="top"><literal>Class</literal></entry>
  242. <entry align="left" valign="top"><literal>Value Type</literal></entry>
  243. <entry align="left" valign="top"><literal>Default</literal></entry></row>
  244. <row>
  245. <entry align="left" valign="top"><literal>localterminal</literal></entry>
  246. <entry align="left" valign="top"><literal>LocalTerminal</literal></entry>
  247. <entry align="left" valign="top"><literal>string</literal></entry>
  248. <entry align="left" valign="top">``Dtterm''</entry></row>
  249. <row>
  250. <entry align="left" valign="top"><literal>remoteTerminals</literal></entry>
  251. <entry align="left" valign="top"><literal>RemoteTerminals</literal></entry>
  252. <entry align="left" valign="top"><literal>string</literal></entry>
  253. <entry align="left" valign="top">``Dtterm''</entry></row>
  254. <row>
  255. <entry align="left" valign="top"><literal>waitTime</literal></entry>
  256. <entry align="left" valign="top"><literal>WaitTime</literal></entry>
  257. <entry align="left" valign="top"><literal>number</literal></entry>
  258. <entry align="left" valign="top">3</entry></row></tbody></tgroup></informaltable>
  259. <variablelist>
  260. <varlistentry><term><literal>LocalTerminal</literal></term>
  261. <listitem>
  262. <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
  263. use. The default terminal emulator is &cdeman.dtterm;.</para>
  264. </listitem>
  265. </varlistentry>
  266. <varlistentry><term><literal>RemoteTerminals</literal></term>
  267. <listitem>
  268. <para>Defines a comma-separated list of host and terminal emulator pairs.
  269. When a remote <systemitem class="Constant">COMMAND</systemitem> action is
  270. executed on one of the hosts in the list, the terminal emulator associated
  271. with that host is used for that command. The list is passed to the terminal
  272. emulator using the <literal>&minus;e</literal> argument. (Thus, if another
  273. terminal emulator than <command>dtterm</command> is used, it must support
  274. the <literal>&minus;e</literal> argument. <![ %CDE.C.CDE; [See <command>xterm</command>(1). ]]></para>
  275. </listitem>
  276. </varlistentry>
  277. <varlistentry><term><literal>WaitTime</literal></term>
  278. <listitem>
  279. <para>Used to assign an alternative integer value, in seconds, to the threshold
  280. 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
  281. unmapped before the user has a chance to read the standard error from the
  282. 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
  283. 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>
  284. </listitem>
  285. </varlistentry>
  286. </variablelist>
  287. </refsect1><refsect1>
  288. <title>RETURN VALUE</title>
  289. <para>Upon successful completion, the <function>DtActionInvoke</function>
  290. function returns a <structname role="typedef">DtActionInvocationID</structname>.
  291. The ID can be used in subsequent execution management services <![ %CDE.C.CDE; [(DtAction) ]]>calls
  292. to manipulate the actions while they are running. <structname role="typedef">DtActionInvocationID</structname>s are only recycled after many have been
  293. generated.</para>
  294. </refsect1><refsect1>
  295. <title>APPLICATION USAGE</title>
  296. <para>The caller should allocate space for the array of structures describing
  297. the objects to be provided as arguments to the action. The caller can free
  298. the memory after <function>DtActionInvoke</function> returns.</para>
  299. <para>Since <function>DtActionInvoke</function> spawns subprocesses to start
  300. local actions, the caller should use <function>waitpid</function>(2) instead
  301. of <function>wait</function>(2) to distinguish between processes started by
  302. the action service and those the caller starts.</para>
  303. </refsect1><refsect1>
  304. <title>EXAMPLES</title>
  305. <para>Given the following action definition:</para>
  306. <informalexample remap="indent">
  307. <programlisting>ACTION Edit
  308. {
  309. LABEL "Text Edit Action"
  310. ARG_CLASS BUFFER, FILE
  311. ARG_TYPE TEXT
  312. TYPE COMMAND
  313. WINDOW_TYPE TERMINAL
  314. EXEC_STRING "textedit %Args%"
  315. DESCRIPTION This action invokes the "textedit" command on
  316. an arbitrary number of arguments. A terminal
  317. emulator is provided for this action's I/O.
  318. EXEC_HOST and CWD are not specified so the
  319. defaults are used for both quantities.
  320. }</programlisting>
  321. </informalexample>
  322. <para>The following call invokes the action
  323. <symbol role="Message">Edit</symbol> on the arguments
  324. <emphasis>aap</emphasis> supplies:</para>
  325. <informalexample remap="indent">
  326. <programlisting> DtActionInvoke(w, "Edit", aap, 3, NULL, NULL, NULL, 1,
  327. myCallback, myClientData);</programlisting>
  328. </informalexample>
  329. <para>The working directory for the action defaults to the current working
  330. directory.
  331. The execution host is the default execution host.</para>
  332. <para>If the variable
  333. <emphasis>aap</emphasis> points to an array of
  334. <literal>ActionArg</literal> data structures
  335. containing the following information:</para>
  336. <informalexample remap="indent">
  337. <programlisting>{
  338. argClass = DtACTION_FILE;
  339. struct {
  340. name="/myhome/file1.txt";
  341. } file;
  342. }</programlisting>
  343. </informalexample>
  344. <informalexample remap="indent">
  345. <programlisting>{
  346. argClass = DtACTION_FILE;
  347. struct {
  348. name="file2.txt";
  349. } file;
  350. }</programlisting>
  351. </informalexample>
  352. <informalexample remap="indent">
  353. <programlisting>{
  354. argClass = DtACTION_BUFFER;
  355. struct {
  356. bp=(void *) myEditBuffer;
  357. size=lengthOfMyEditBuffer;
  358. type=NULL;
  359. name="Doc1.txt"
  360. writable=TRUE;
  361. } buffer;
  362. }</programlisting>
  363. </informalexample>
  364. <para>and the current working directory is
  365. <Filename>/cwd</Filename>, then the
  366. <symbol role="Message">Edit</symbol> action results in the execution string:
  367. </para>
  368. <informalexample remap="indent">
  369. <programlisting>textedit /myhome/file1.txt /cwd/file2.txt /myhome/.dt/tmp/Doc1.txt
  370. </programlisting>
  371. </informalexample>
  372. <para>When the action completes,
  373. <emphasis>myCallback</emphasis> is called and
  374. the callback returns the buffer argument.</para>
  375. </refsect1><refsect1>
  376. <title>SEE ALSO</title>
  377. <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;;
  378. ]]>&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>
  379. </refsect1></refentry>
  380. <!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
  381. <?Pub *0000053895>