Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DtActionInvoke(library call)			  DtActionInvoke(library call)

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
       The  DtActionInvoke  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.

       The  actions  and  data	types databases	must be	initialized and	loaded
       (using DtInitialize(3) and DtDbLoad(3)) before DtActionInvoke  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 ar-
       ray  are	assigned to the	option argument	keywords referenced in the ac-
       tion definition (see dtactionfile(4)). The nth item is assigned to key-
       word %Arg_ n%. For example, the second item is assigned to %Arg_2%.

       The argCount argument is	the number of action arguments provided	in the
       array args references.

       The termOpts argument is	a string providing special execution  informa-
       tion  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 emu-
       lator 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  di-
       rectory for the action. File name arguments are interpreted relative to
       this directory, which must reside in the	local file name	space (for ex-
       ample, /usr/tmp or /net/hostb/tmp).  This value is only used if the ac-
       tion 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).

       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 invo-
       cation 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 statusUpdateCb is set to	 NULL,
       subsequent  action  status  is  not  returned. (See Dt/Action.h - DtAc-
       tion(5) for a list of all DtActionStatus	codes, and  see	 DtActionCall-
       backProc(3)  for	details	on statusUpdateCb and a	list of	specific DtAc-
       tionStatus codes	it can return.)

       The client_data argument	is optional data to be passed to the statusUp-
       dateCb 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	 argu-
       ments  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 argu-
       ments are supplied to an	action requiring zero or one  arguments,  then
       that  action  is	invoked	once for each of the supplied arguments. Argu-
       ments 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 argu-
       ments passed to DtActionInvoke.

       The DtActionInvoke function accepts a pointer  to  an  array  of	 DtAc-
       tionArg	structures  describing the objects to be provided as arguments
       to the action. The args structure can be	modified or freed after	 DtAc-
       tionInvoke returns.

       A  single  call	to DtActionInvoke may initiate several actions or mes-
       sages. 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	(DtAc-
       tion) 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 ac-
       tion 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 construc-
       tion 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 per-
       mission bits on the temporary file are set according  to	 the  writable
       field  and  the IS_EXECUTABLE attribute from the	action service associ-
       ated 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 con-
       figured 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 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*localTer-
       minal: xterm to set the terminal	emulator to xterm(1)  for  the	dtfile
       client only.  (See dtactionfile(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 emulator 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 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	 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 pro-
		 vides a workaround to this problem. If	a TERMINAL window com-
		 mand 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 sec-
		 onds.

RETURN VALUE
       Upon successful completion, the DtActionInvoke function returns a DtAc-
       tionInvocationID.   The	ID can be used in subsequent execution manage-
       ment 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  sup-
       plies:

	       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  re-
       turns the buffer	argument.

SEE ALSO
       Dt/Action.h  -  DtAction(5),   xterm(1),	 XtFree(3),  XtMalloc(3), DtD-
       bLoad(3),  DtInitialize(3),  DtActionCallbackProc(3),  dtactionfile(4),
       dtdtfile(4), dtdtsfile(4).

						  DtActionInvoke(library call)

NAME | SYNOPSIS | DESCRIPTION | RESOURCES | RETURN VALUE | APPLICATION USAGE | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DtActionInvoke&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help