deskcommands(XC)

Deskshell commands -- commands of the Deskshell command language

Description

This manual page gives an alphabetical list of the Deskshell commands, built into the Desktop. The syntax and description for all commands are provided; examples are included for most commands. When applicable, returned status values are also included for the relevant commands.

For information on Deskshell syntax and control constructs, see the deskshell(XC) manual page.

absreadlink

Returns the absolute pathname of the contents of a symbolic link.

Syntax

absreadlink pathname . . .

Result

If the argument is a symbolic link, the result is the absolute pathname corresponding to the contents of the link. Otherwise, it is the canonical form of the argument.

Status

Only on argument errors.

Example

For example, if the file /a/b/c is a symbolic link reading ../x, the command:

   absreadlink /a/b/c

returns the string ``/a/b/../x''.

NOTE: This is not the same as the canonical form of the contents of the link, which is ``/a/x''.

See also:

followlink, which returns the absolute pathname of the final destination of a link
readlink, which returns the contents of a link

actions_of [act]

Emulates an icon trigger.

Syntax

actions_of trigger staticobject [dynamicobject . . .] [-d dynamicdesktop]
[-s staticdesktop] [-D dynamicposn] [-S staticposn]

where:

trigger: a trigger name
staticobject: the object triggered
dynamicobject: the object(s) dragged or selected
staticdesktop: the open desktop that the static objects are on
dynamicdesktop: the open desktop that the dynamic objects are on
staticposn: the nominal positions of the static objects
dynamicposn: the nominal position of the first dynamic object

Description

The actions_of command (abbreviated act) emulates an icon trigger action. You can specify either a static or dynamic trigger.

The rules are searched to locate a trigger_action clause for trigger and staticobject. The rules for a staticdesktop, if specified, will be used in the search. Each actions_of command starts a new thread, so the actions are executed asynchronously.

The following variables are set in the new thread:

Variable Value

static_arg staticobject in canonical form

dynamic_args dynamicobject in canonical form

s_desktop staticdesktop, or an empty list

d_desktop dynamicdesktop, or an empty list

s_position staticposn, or V if not specified

d_position dynamicposn, or V if not specified

trigger trigger

as dynamic_args

Variable	Value
static_arg	*staticobject* in canonical form
dynamic_args	*dynamicobject* in canonical form
s_desktop	*staticdesktop*, or an empty list
d_desktop	*dynamicdesktop*, or an empty list
s_position	*staticposn*, or V if not specified
d_position	*dynamicposn*, or V if not specified
trigger	*trigger*
	as dynamic_args

Status

OK (0): the command was successful
NOTRIGGER (1): the static argument does not have an action for the specified trigger

Example

The following example defines the action when a user double-clicks the icon for a file with the extension .txt to be the same as dragging the icon onto the Edit.obj object in the General tools directory:

   icon_rules
   {
      *.txt /F
      {
   
         picture=textdoc.px;
         trigger_action: activate
         {
             actions_of drop $XDTHOME/tools/General.ts/Edit.obj static_arg
         }
      }
   }

See also:

do_actions_of, which executes the actions synchronously, in the same thread
drop_in_actions_of, which emulates a window background trigger
menu_actions_of, which emulates selection of a menu command

basename

Returns the basenames of its arguments.

Syntax

basename pathname . . .

Result

The argument is converted to canonical form, and the result is then the part that follows the last slash. If the argument specifies the Root directory, the result is slash (/).

Status

Only on argument errors.

Example

The following example runs vi with $static_arg in a shell window, and uses basename to give the shell window the title: ``Edit:'' basename.

   name=`(basename $static_arg)
   shell -n 'Edit: '^$name vi $static_arg

The following examples illustrate the command:

Pathname Result

/usr/code.bin code.bin

/a/b/c /d/e f (c e f)

Pathname	Result
/usr/code.bin	code.bin
/a/b/c /d/e f	(c e f)

See also:

canonical, which converts its argument to canonical form
dirname, which returns the directory name
extension, which returns the extension
relativepath, which returns the pathname relative to the user's home directory

break

Exits from loop constructs.

Syntax

break [depth]

where:

depth: the number of enclosing for, while, or until loops to exit from. The default is ``1''.

Description

The command exits from the specified number of loops, provided they all lie within the currently executing function, if any. If there are insufficient enclosing loops, the command exits from all of them.

Status

Only on argument errors.

Example

This example shows an infinite loop. It keeps asking ``Are you ready to continue?'' as long as No is clicked. If Yes is clicked then break breaks out of the loop.

   while true
   do  
      if yni 'Are you ready to continue?'
      then
         break
      fi
   done

See also:

continue, which continues execution of an outer loop construct.

bring_to_front [btf]

Brings directory or desktop windows to the front or back of the stack.

Syntax

bring_to_front [-flags] { [dir or opendesktop] . . . }

where:

flags

can be one of the following:

raise the named windows to the front of all displayed windows
lower the named windows to the back of all displayed windows

dir

the name of the directory window

opendesktop

the name of the open desktop

Description

The named directory windows and desktops, if open, are moved to the front or the back of the stack of displayed windows, with the one named first placed at the extreme top or bottom, respectively.

Status

The variable status is set to the number of directories and desktops named that were not visible.

Example

The following command defines a directory Edit menu with a Send to Back menu command:

   menu: DirEditMenu
   {
     menu_item: Send to Back _B__
     {
        bring_to_front -b $static_arg
     }
   }

builtin

Specifies that the following command is built-in.

Syntax

builtin command [args . . .]

where:

command: a built-in Deskshell command
args: arguments to the command

Status

The command sets the value of status as follows:

XCL_NOTCOMMAND (768): no built-in command of the specified name was found

Example

The following example sets $x1 to ``nowhere'' and $x2 to ``/u/claudio'':

   function pwd { return 'nowhere' }
   cd /u/claudio
   x1='pwd
   x2='(builtin pwd)

See also:

call, which specifies a function
external, which specifies an external command

call

Specifies that the following command is a function.

Syntax

call function [args . . .]

where:

function: a function name
args: arguments to the function

Status

The command sets the value of status as follows:

XCL_NOTCOMMAND (768): no function of the specified name was found

Example

The following example calls the for_info user's function:

   call for_info 'Hello'

See also:

builtin, which specifies a Deskshell command
external, which specifies an external command

canonical

Converts its argument to canonical (i.e., non-redundant) form.

Syntax

canonical pathname . . .

Result

Relative pathnames are converted to absolute pathnames.
Redundant slashes are removed.
All ``.'' and ``..'' elements are eliminated, except when they follow the last slash in the argument.

Status

Only on argument errors.

Example

The following examples illustrate the command:

Pathname Result

a/b/../c /u/claudio/a/c

/a/b/c/.. /a/b/c/..

/a/b/c/../ /a/b

/a/b/c/k/../d/./e /a/b/c/d/e

Pathname	Result
a/b/../c	/u/claudio/a/c
/a/b/c/..	/a/b/c/..
/a/b/c/../	/a/b
/a/b/c/k/../d/./e	/a/b/c/d/e

See also:

basename, which returns the basename
dirname, which returns the directory name
extension, which returns the extension
relativepath, which returns the path relative to the user's home directory

cd

Sets the current directory to its argument.

Syntax

cd [dir . . .]

Description

The current directory of the thread is changed. If there are no arguments, the effect is as if the arguments were the contents of the variable $home.

Each argument is processed as follows until a searchable directory is located. The current directory of the thread is changed to that directory, and the remaining arguments are ignored.

If an argument begins with a slash it is taken to be the name of a directory without modification.
Otherwise, each string in the value of the variable $cdpath is taken in order. If the argument contains a slash, then ``.'' the current directory (.) is added at the front of this list.
Each string from $cdpath in turn is prefixed to the argument (with an intervening slash) to generate a filename.
Each of these is checked in turn until a searchable directory is found or there are no more strings in the list.
If no directory was found, this sequence is repeated with the next argument.

Thus directory names containing ``/'' are first checked relative to the current directory before using $cdpath. Simple directory names, not containing ``/'', are only checked using $cdpath.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following commands:

   cd /home
   cdpath=(/a/b /c)
   cd x/y /p/8 z

make the current directory the first of the following directories that exist:

   /home/x/y
   /a/b/x/y
   /c/x/y
   /p/8
   /a/b/z
   /c/z

See also:

pwd, which returns the current directory

check [chk]

Checks and, if necessary, updates icons.

Syntax

check [-flags] [object . . .]

where:

flags

can be one of the following:

D: check the contents of the objects, rather than the objects themselves. The objects must be desktops or directories.
R: if an object no longer exists, remove it rather than changing its picture.

object

the objects to be checked. If no objects are specified, this is equivalent to specifying the names of all icons in all open desktops.

Description

The check command is used to update an icon to reflect the current state of the filing system.

The rules for the named objects are checked to determine if any icon for the objects should have a different picture or title. If so, the picture or title is changed.

Status

The command sets the value of status as follows:

OK (0): the command completed successfully
Special (>= 768): an argument error occurred

Example

The following example uses the variation class to animate the Home icon between a closed version and an open version when the directory icon is activated:

   icon_rules
   {
     %$HOME$/DWXMO
     {
       picture=home_c.px ;
       trigger_action: activate
       {
          variation_class 1 $static_arg
          check $static_arg
          display_directory $static_arg
       }
     }
     %$HOME$/DWXM1
     {
       picture=home_o.px ;
     }
   }

See also:

pixmap_check, which checks pictures and updates icons

close_desktop [cldt]

Closes specified desktop windows.

Syntax

close_desktop [-flags] [desktop . . .]

where:

flags

can be one of the following:

m: close the main Desktop
N: do not save the Desktop contents.

desktop

desktops to close. If no desktops are named and the m flag is not specified, then all desktops are closed.

Status

The variable status holds the number of desktops specified that were not open.

Example

The following script in a desktop rule file makes a double-click on the desktop background close the desktop window:

   drop_in_action : report
   {
      close_desktop $static_arg
   }

See also:

open_desktop, which opens specified desktops

close_directory [cdw]

Closes open directory windows.

Syntax

close_directory [dir . . .]

where:

dir: the names of directories to close. If no arguments are specified, all open directories are closed.

Status

The number of directories specified that were not open.

Example

A directory Close function could be defined as follows:

   menu_item: Close _l_Ctrl<Key>C_Ctrl+C
   {
     close_directory $static_arg
   }

See also:

display_directory, which opens specified directories

continue

Continues execution of a loop construct.

Syntax

continue [depth]

where:

depth: the number of the enclosing loop to continue executing. The default is ``1''.

Description

The command starts executing the next iteration of the specified depth of enclosing for, while, or until loops. If depth is greater than the number of enclosing loops, the outermost one is started at its next iteration.

Status

Only on argument errors.

Example

This example shows a for loop for removing a list of files. It asks you if you wish to remove the file, and if the answer is ``No'', it will continue to the next file, i.e., it will miss out the rest of the loop and will continue with the next icon in the loop list.

   for icon in $dynamic_args
   do
     yni 'Do you wish to remove' $icon '?'
     if -eq $status 1
     then
       continue
     fi
     remove $icon
   done

NOTE: This example is not the most efficient way of performing the desired task, but illustrates use of the continue command.

See also:

break, which exits from loop constructs

copy_desktop [cdt]

Saves a specified desktop.

Syntax

copy_desktop [file] [-d opendesktop]

where:

file: the name of the file the rules are saved to. Defaults to the name of the desktop.
opendesktop: the name of the desktop to save. Defaults to the main Desktop.

Description

The contents of the named desktop are saved, with its rules, into file.

Status

The command sets the value of status as follows:

OK (0): the desktop was saved successfully
NOTOPEN (1): the desktop was not open
ERROR (255): another error occurred

Example

The following rule saves the desktop, if the user has access:

   {
      if match `(fileclass $static_arg) F?W*
      then copy_desktop -d $static_arg
      else for_info -h prop -t save 'Not allowed'
      fi
   }

copy_into [cpi]

Copies files into a directory.

Syntax

copy_into dir file . . .

Description

Copies the specified files into directory dir. If the directory window is open, new icons will appear in the window.

Files are not copied if they are already in the directory, or if there exists a file in the directory with the same basename. If two or more files with the same basename are specified, it is undefined which is actually copied.

Status

The number of files not copied.

Example

For example:

   copy_into /a /b/c d/e

copies the file /b/c to /a/c, and the file d/e to /a/e.

See also:

link_into, which links files into a directory
move_into, which moves files into a directory
symlink_into, which symbolically links files into a directory

declare exported

Declares specified variables as exported.

Syntax

declare exported [flags] [variable. . .]

where:

flags

can be one of the following:

-all: all present and future thread variables should be exported, including overridden variables
-:all: all present and future global variables should be exported
-new: all new thread variables should be exported, including new overridden variables
-:new: all new global variables should be exported

variable

variables to be exported

Description

The named variables in the current thread (or the named global variables for those whose name is prefixed by a colon) are declared to be exported. When a process is run from within the thread, these variables will appear in the environment of that process.

The property of being exported is part of the value of a variable. Thus, it is inherited when the variable is copied, when a child thread is created, or the variable is overridden. Similarly, if the variable is currently overridden, this does not affect whether or not the previous value is exported.

If a named thread variable does not exist but the corresponding global variable does, the thread variable is created with the same value as the global variable. In any case, if the variable does not exist it is created with an empty list for its value.

Example

The following example exports NEWHOME:

   NEWHOME=`{ pwd }
   declare exported NEWHOME

declare not_exported

Declares specified variables as not to be exported.

Syntax

declare not_exported [flags] [variable . . .]

where:

flags

can be one of the following:

-all: no present or future thread variables should be exported, including overridden variables
-:all: no present or future global variables should be exported
-new: no new thread variables should be exported, including new overridden variables
-:new: no new global variables should be exported

variable

variables not to be exported

Description

The named variables in the current thread (or the named global variables for those whose name is prefixed by a colon) are declared to be not exported. When a process is run from within the thread, these variables will not appear in the environment of that process.

Example

The following example makes NEWHOME not exported, so any new threads will not contain NEWHOME:

   NEWHOME=`{ pwd }
   declare not_exported NEWHOME

die

Terminates the Desktop client.

Syntax

die [-flags]

where flags can be:

i: terminate without prompting the user
N: do not save any open desktops

Description

The die command causes the Desktop to enter a termination state. Depending on the resources and user response to prompts, this might terminate the Desktop client session.

Once in termination state, all open desktop and directory windows are closed, as if by the close_desktop and close_directory commands, and the system thread starts executing the final_actions clauses in appropriate rule files.

When the system thread and all desktop and directory threads have exited, the Desktop process exits.

Status

The command sets the value of status as follows:

CANCELED (2): the command was canceled by the user
ERROR (255): an error occurred

Example

The following example displays a yni dialog box to allow the user to close down the Desktop:

   if yni 'Do you really want to close X.desktop?'
   then
     die
   fi

dirname

Returns the directory name of its argument.

Syntax

dirname pathname . . .

Description

The argument is converted to canonical form, and the result is then the part that precedes the last slash. If the argument is root, or a file in the Root directory, the result is slash followed by dot (/.). The result is the directory name.

Status

Only on argument errors.

Example

The following example defines a rule so that double-clicking on a directory icon with the alternate mouse button displays the parent directory window:

   icon_rules
   {
     * /DRX
     {
       picture=dir_read.px;
   
       trigger_action: alt_activate
       {
         display_directory `(dirname $static_arg/)
       }
     }
   }

See also:

basename, which returns the basename
canonical, which converts its argument to canonical form
extension, which returns the extension
relativepath, which returns the pathname relative to the user's home directory

display_directory [odw]

Opens or redisplays a window showing the contents of a directory.

Syntax

display_directory [-flags] [-f format] [dir [dir2]]

where flags can consist of a list of letters, at most one from each of the following sets:

Sort order

a: sort alphabetically
A: sort alphabetically by title
c: sort by file class
d: sort by major file class and then alphabetically
D: sort by major class and then alphabetically by title
F: leave format unchanged, rather than reverting to default. The format parameter must not be specified.
s or u: sort by size
t: sort by time of last change

Display options

i: display icons
n: display names and additional information

Redisplay options

v: redisplay window only if directory has changed

Additional parameters

dir, dir2: directories to be displayed; see description below
format: see below

Description

Major class means one of the classes B, C, D, F, G, I, or P. When names are being displayed, with the -n option, the text displayed consists of the format string with the following ``%'' character sequences replaced with information about the file or directory, as shown in the following table:

Sequence Description

%B the basename of the file

%C the class of the file

%I the title of the object used in icon mode

%P the absolute pathname of the file

%R the basename of the file

%S the size of the file, in bytes

%T the time the file was last changed

%% a percent character

The following default formats are used if a sort order is specified in name display mode:

Sequence	Description
%B	the basename of the file
%C	the class of the file
%I	the title of the object used in icon mode
%P	the absolute pathname of the file
%R	the basename of the file
%S	the size of the file, in bytes
%T	the time the file was last changed
%%	a percent character

Sort order Default format

a, A, d, or D %B

c %C %B

s or u %S %B

t %T %B

The following options are available:

Sort order	Default format
a, A, d, or D	%B
c	%C %B
s or u	%S %B
t	%T %B

Option Description

No directories specified All open directory windows are modified according to flags. Any property not specified is unaffected.

One directory specified If no window is open for dir, a window is opened and properties set according to flags, with v flag ignored and unspecified sort order and display option defaulting to a and i, respectively.
If a window is open for dir, it is modified according to flags, with unspecified properties unaltered.

Same directory is specified twice
(i.e., dir=dir2) If a window is open for dir, it is modified according to flags, with unspecified properties unaltered; otherwise nothing happens.

Two different directories specified If there is no window open for dir2, opens it in the window used for dir. Otherwise, the dir2 window is closed and its contents are re-displayed in the window for dir.

Option	Description
No directories specified	All open directory windows are modified according to *flags*. Any property not specified is unaffected.
One directory specified	If no window is open for *dir, a window is opened and properties set according to flags, with v flag ignored and unspecified sort order and display option defaulting to a and i, respectively. If a window is open for dir, it is modified according to flags*, with unspecified properties unaltered.
Same directory is specified twice (i.e., *dir=dir2*)	If a window is open for *dir, it is modified according to flags*, with unspecified properties unaltered; otherwise nothing happens.
Two different directories specified	If there is no window open for *dir2, opens it in the window used for dir. Otherwise, the dir2* window is closed and its contents are re-displayed in the window for *dir*.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following example shows how the display_directory command could be used to define a simple directory Sort cascade menu:

   menu: DirSortMenu
   {
     menu_item: by Title _T__
       { display_directory -a $static_arg }
     menu_item: by Time _i__
       { display_directory -t $static_arg }
     menu_item: by Size _S__
       { display_directory -s $static_arg }
   }

See also:

open_desktop, which opens a desktop window

do_actions_of [do_act]

Emulates an icon trigger.

Syntax

do_actions_of trigger staticobject [dynamicobject . . .] [-d dynamicdesktop]
[-s staticdesktop] [-D dynamicposn] [-S staticposn]

where:

trigger: a trigger name
staticobject: the object triggered
dynamicobject: the objects dragged or selected
dynamicdesktop: the open desktop that the dynamic objects are on
staticdesktop: the open desktop that the static objects are on
dynamicposn: the nominal position of the dynamic objects
staticposn: the nominal position of the static objects

Description

The rules are searched to locate a trigger_action clause for trigger and staticobject. The rules for the staticdesktop, if specified, will be used in the search. The command is a synchronous version of actions_of. The actions are executed in the same thread. The following variables are set:

Variable Value

trigger trigger

static_arg staticobject in canonical form

dynamic_args dynamicobject in canonical form

s_desktop staticdesktop, or an empty list

d_desktop dynamicdesktop, or an empty list

s_position staticposn, or V if not specified

d_position dynamicposn, or V if not specified

* as dynamic_args

Variable	Value
trigger	*trigger*
static_arg	*staticobject* in canonical form
dynamic_args	*dynamicobject* in canonical form
s_desktop	*staticdesktop*, or an empty list
d_desktop	*dynamicdesktop*, or an empty list
s_position	*staticposn*, or V if not specified
d_position	*dynamicposn*, or V if not specified
*	as dynamic_args

Status

The command sets the value of status to the return code of the action if the static argument has an action for the specified trigger, or as follows:

NOTRIGGER (1): the static argument has no action for the trigger

Example

The standard definition of the Duplicate function in the directory File menu is:

   menu_item: Duplicate _u__
   {
     do_actions_of duplicate $static_arg $dynamic_args
   }

This finds the trigger_action: duplicate clause for the object in $static_arg, the object is triggered, and runs it, passing the current value of $dynamic_args as the objects for the trigger action to use as its $dynamic_args.

See also:

actions_of, which executes the actions of a trigger in a new thread
do_drop_in_actions_of, which emulates a window background trigger
do_menu_actions_of, which emulates selection of a menu command

do_drop_in_actions_of [do_drp]

Emulates a window background trigger.

Syntax

do_drop_in_actions_of trigger staticobject [dynamicobject . . .]
[-d dynamicdesktop] [-s staticdesktop] [-D dynamicposn] [-S staticposn]

where:

trigger: a window background trigger name
staticobject: the object triggered
dynamicobject: the objects dragged or selected
dynamicdesktop: the open desktop that the dynamic objects are on
staticdesktop: the open desktop that the static objects are on
dynamicposn: the nominal position of the dynamic objects
staticposn: the nominal position of the static objects

The rules are searched to locate a drop_in_action clause for trigger and staticobject. The rules for the staticdesktop, if specified, will be used in the search. The command is a synchronous version of drop_in_actions_of. The actions are executed in the same thread. The following variables are set:

Variable	Value
trigger	*trigger*
static_arg	*staticobject* in canonical form
dynamic_args	*dynamicobject* in canonical form
s_desktop	*staticdesktop*, or an empty list
d_desktop	*dynamicdesktop*, or an empty list
s_position	*staticposn*, or V if not specified
d_position	*dynamicposn*, or V if not specified
*	as dynamic_args

Status

The command sets the value of status to the return code of the action if the static argument has an action for the specified trigger, or as follows:

NOTRIGGER (1): the static argument has not action for the trigger

Example

A menu command to emulate the report trigger could be written:

   menu_item: Report _p__
   {
     do_drop_in_actions_of report $static_arg $dynamic_args
   }

See also:

do_actions_of, which executes the actions of an icon trigger in the same thread
do_menu_actions_of, which emulates selection of a menu command
drop_in_actions_of, which executes the actions of a window background trigger in a new thread

do_menu_actions_of [do_menu]

Executes a command from a menu synchronously.

Syntax

do_menu_actions_of menu item [object . . .] [-d desktop] [-D directory]
[-s staticobj]

where:

menu: the name of the menu
item: the item tag, or a numeric position, in the menu_item clause referenced by menu
object: arguments to be passed to the menu script in dynamic_args
staticobj: object passed to the menu script in $static_arg
desktop: a desktop whose rules are to be used in locating the menu
directory: a directory whose rules are to be used in locating the menu

Description

Performs the same action as if the user had chosen menu command cmd from menu. The command is executed in the same thread. The following variables are set:

static_arg: the first of staticobj, directory, or desktop to have been specified; otherwise an empty list
dynamic_args: the objects, with filenames in canonical form
d_desktop: desktop, or an empty list

Status

The command sets the value of status to the return code of the action if the static argument has an action for the trigger, or:

NOTRIGGER (1): the static argument has no action for the trigger

Example

The following rule specifies that if any .bak file receives a menu trigger, it will trigger the menu action of command 11 in the directory File menu, which might be (for example) Discard.

   icon_rules
   {
     *.bak /F
     {
        trigger_action: menu
        {
        do_menu_actions_of DirFileMenu 11 $static_arg
        }
     }
   }

See also:

do_actions_of, which emulates an icon trigger
do_drop_in_actions_of, which emulates a window background trigger
menu_actions_of, which executes the actions asynchronously

drop_in_actions_of [drp]

Emulates a window background trigger.

Syntax

drop_in_actions_of trigger staticobject [dynamicobject . . .]
[-d dynamicdesktop] [-s staticdesktop] [-D dynamicposn] [-S staticposn]

where:

trigger: a window background trigger name
staticobject: the object triggered
dynamicobject: the objects dragged or selected
dynamicdesktop: the open desktop that the dynamic objects are on
staticdesktop: the open desktop that the static objects are on
dynamicposn: the nominal position of the dynamic objects
staticposn: the nominal position of the static objects

Description

The rules are searched to locate a drop_in_action clause for trigger and staticobject. The rules for the staticdesktop, if specified, will be used in the search. Each drop_in_actions_of command starts a new thread, so the actions are executed asynchronously. The following variables are set in the new thread:

Variable	Value
static_arg	*staticobject* in canonical form
dynamic_args	*dynamicobject* in canonical form
s_desktop	*staticdesktop*, or an empty list
d_desktop	*dynamicdesktop*, or an empty list
s_position	*staticposn*, or V if not specified
d_position	*dynamicposn*, or V if not specified
trigger	*trigger*
*	as dynamic_args

Status

The command sets the value of status as follows:

OK (0): the command was successful
NOTRIGGER (1): the static argument does not have an action for the specified trigger

Example

The following example maps the trigger alt_report onto the trigger report, so that they have the same effect.

   drop_in_action: alt_report
   {
      drop_in_actions_of report $static_arg
   }

See also:

actions_of, which emulates selection of an icon trigger
do_drop_in_actions_of, which executes the actions synchronously, in the same thread
menu_actions_of, which emulates selection of a menu command

duplicate_file [dup]

Duplicates the file.

Syntax

duplicate_file file [-b basename]

where:

file: the name of the file to be duplicated
basename: the basename for the duplicate file (any leading directory is removed)

Description

The specified file is duplicated (by copying) in the same directory. If basename is not specified, the directory window must be displayed, and the user is prompted for a name for the duplicate file. The entered name is placed in the local variable $entered_name.

The argument must be a regular file. If no arguments or more than one argument is specified, then a warning will be displayed, and the command will be ignored.

Status

The command sets the value of status as follows:

OK (0): the duplicate was successful
CANCELED (2): the duplicate was canceled by the user
ERROR (255): an error occurred

Example

The following example uses the duplicate_file command to define a duplicate trigger action:

   trigger_action: duplicate
   {
     if -gt $#dynamic_args 1
     then
       for_info -h select -t Duplicate 'You may only duplicate one item.'
       exit
     fi
     duplicate_file $dynamic_args
   }

duplicate_link [dupl]

Gives a second link to a file.

Syntax

duplicate_link file [-b basename]

where:

file: the file to which to link
basename: the basename for the duplicate file (any leading directory is removed)

Description

The argument must not be a directory. Unless exactly one positional argument is specified, the Desktop will warn the user and the command will be ignored.

The specified file is given a second link in the same directory. If basename is not specified, that directory must be open, and the user is prompted for a name for the new link. The entered name is placed in the local variable $entered_name.

Status

The command sets the value of status as follows:

OK (0): the link was successful
CANCELED (2): the link was canceled by the user
ERROR (255): an error occurred

Example

The following example uses the duplicate_link command to define a link trigger action:

   trigger_action: link
   {
     if -gt $#dynamic_args 1
     then
       for_info -h select -t Link 'You may only link one item.'
       exit
     fi
     duplicate_link $dynamic_args
   }

duplicate_symlink [dupsl]

Creates a symbolic link to a file.

Syntax

duplicate_symlink [-flags] file [-b basename]

where:

flags: can be r to create a relative link
file: the name of the file to create a link to
basename: the basename for the duplicate file (any leading directory is removed)

Description

Unless exactly one positional argument is specified, the Desktop will warn the user and the command will be ignored. A symbolic link to the specified file is created in the same directory. If basename is not specified, that directory must be open, and the user is prompted for the name for the symbolic link. The entered name is placed in the local variable $entered_name.

By default, the link will contain an absolute name. The r flag causes it to contain a relative name, which will just be a basename.

Status

The command sets the value of status as follows:

OK (0): the command was successful
CANCELED (2): the command was canceled by the user
ERROR (255): an error occurred

Example

The following shows the difference between an absolute and relative link:

after the command duplicate_symlink /a/b/c -b x1
- the name of the link is /a/b/x1
- the link contains /a/b/c
after the command duplicate_symlink /a/b/c -r -b x2
- the name of the link is /a/b/c
- the link contains c

If you move /a/b/x1 and /a/b/x2 into /p/q, then:

x1 still points to /a/b/c
x2 points to /p/q/c

dynamic_rule [idr]

Installs a dynamic rule in a specified position in the rule database.

Syntax

dynamic_rule [-flags] [-A after] [-B before] name word . . .

where:

flags

can be one of the following:

x: execute the initial_actions clause, if present
f: read the rule from a specified file
t: brings together all rules with this name
a: place after the last rule with the name name
b: place before the first rule with the name name
F: place at the front of all other rules

after

the names of rules after which the rule is placed

before

the names of rules before which the rule is placed

name

a name to identify the dynamic rule

word

strings or filenames, as specified by flags

Description

The remaining arguments or, if the -f flag is specified, the contents of the files named by the remaining arguments, are concatenated together separated by single spaces.

The resulting string is installed as a new dynamic rule, with the specified name. Its position is determined by flags, and the after and before options. The default is after all other rules.

The initial_actions clause will only be executed if the -x flag is present.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): a parsing error has occurred

If a parsing error occurs, it is undefined how much of the rule has been installed. If a rule of the given name already exists, then both rules will have the same name.

Example

The following example temporarily makes a file non-editable:

   dynamic_rule non_edit_c '
     icon_rules
     {
       *.c
       {
         trigger_action: activate
         {
           for_info ''Editing prohibited''
         }
       }
     } '

To cancel the dynamic rule:

   remove_dynamic_rule non_edit_c

To install an exception to allow editing of fred.c:

   dynamic_rule -B non_edit_c edit_fred '
     icon_rules
     {
       fred.c
       {
         ...rules for editing fred.c...
       }
     } '

See also:

remove_dynamic_rule, which removes a dynamic rule

eval

Executes a script.

Syntax

eval command . . .

Description

The arguments are joined together and the result is executed by the thread as if it was a function call with no arguments.

Example

In the following example:

   v1='This is $v1'
   v2='This is $v2'
   v3='This is $v3'
   for i in v1 v2 v3
   do
     eval 'for_info -t ''Value of '$i''' $'$i
   done

the loop is equivalent to:

   for_info -t 'Value of v1' $v1
   for_info -t 'Value of v2' $v2
   for_info -t 'Value of v3' $v3

extension

Returns the extension of its argument.

Syntax

extension pathname . . .

Result

The part of the basename of the argument after the last dot (excluding leading dots), or the empty string if there is no extension.

Status

Only on argument errors.

Example

The following examples illustrate the command:

Pathname Result

/usr/code.bin .bin

.xdtdirinfo null

jim.fred.joe .joe

/.xy.c .c

Pathname	Result
/usr/code.bin	.bin
.xdtdirinfo	*null*
jim.fred.joe	.joe
/.xy.c	.c

See also:

basename, which returns the basename
canonical, which converts its argument to canonical form
dirname, which returns the directory name
relativepath, which returns the pathname relative to the user's home directory

external

Specifies that the following command is an external UNIX command.

Syntax

external command [args . . .]

Status

The command sets the value of status as follows:

XCL_NOTCOMMAND (768): no command of the specified name was found

Example

The following example runs the UNIX command join rather than the Deskshell join command:

   external join file1 file2

See also:

builtin, which specifies a Deskshell command
call, which specifies a function

false

Test whether any argument is false.

Syntax

false [word . . .]

where:

word: an argument which is converted to a number

Status

The command sets the value of status as follows:

YES (0): at least one argument is non-zero (false)
NO (1): all arguments are zero (true), or there are no arguments

Example

The following example displays a dialog box if $list contains a non-zero element:

   if false $list
     for_info 'Not zero'
   fi

See also:

true, which tests whether all arguments are true

fileclass

Returns the class of its argument.

Syntax

fileclass pathname . . .

Result

A list of the classes of the argument, in canonical form. Classes are used to represent the properties of files and directories in a concise form. These properties fall into the following six sets:

File type
Execute permissions
Read/write permissions
Ownership
Symbolic
Variation

A file or directory has one property from each set. The properties are each represented by a character (the letters may be in upper or lower case), so that the class of a file consists of exactly six characters.

For example, an executable file might have the full class definition:

   FXWM-0

The characters used are as follows:

File/Directory types

B: block special file
C: character special file
D: directory
F: regular file
G: ghost (non-existent file)
I: inaccessible file
p: pipe

The codes ``G'' and ``I'' imply the codes ``H'', ``N'', and ``O'' (see below).

Execute permissions

X: the user may execute the file
A: the file has execute permission for someone, but not for the user
N: the file does not have execute permission for anyone

In the case of directories, ``execute'' means the user can look at the files in the directory, otherwise all files in the directory are class ``I''.

Read/write permissions

W: the user may read and write the file
V: the user may read but not write the file, and the file has write permission for someone
K: the user may read the file, and the file does not have write permission for anyone
H: the user may not read the file

In the case of directories, ``read'' means the user can open the directory window and ``write'' means the user can create, delete, or rename files in the directory.

Ownership

M: the user owns the file
O: the user does not own the file

Symbolic

+: the file is a symbolic link
-: the file is not a symbolic link

Variation

0 to 9: variation class of the object

The variation class is used to record the state of an object that can have one of several forms; e.g., a directory that can be open or closed. When the Desktop starts, all objects are given a variation class of ``0''. This can be changed by the variation_class command.

Combining classes

For each set of properties, the letters of the set that appear should be viewed as being separated by the word ``or'', with the groups of letters from different sets being separated by ``and''.

For example, class ``BCNWVO'' is: (``B'' or ``C'') and ``N'' and (``W'' or ``V'') and ``O''.

If no letters of a class appear, then the class is read as if they all appeared. For example, class ``D'' is the same as ``DXANWVKHMO+-0123456789'' (both mean all directories).

A number of extra codes may also be used in classes. These each stand for a common combination of the standard codes:

E: equivalent to ``AX'', executable by somebody
L: equivalent to ``KV'', writable by somebody
Q: equivalent to ``GI'', not a file that exists
R: equivalent to ``KVW'', readable by the user
U: equivalent to ``AN'', not executable by the user
S: equivalent to ``G+'', a symbolic link to nowhere

For example, ``DEO'' and ``DAXO'' have the same meaning.

Sample classes

The following classes are the most useful in rule files:

D: directories
F: files
FE: executable files
FX: files executable by the user
FN: data files
FNW: data files that the user can alter
FNR: data files that the user can read

Example

The following example defines a rule which moves any file or files dropped onto a directory icon with mouse button 1 into that directory:

   icon_rules
   {
     * /D
     {
       trigger_action: drop
       {
         move_into $static_arg $dynamic_args
       }
     }
   }

followlink

Returns the absolute pathname of the final destination of a symbolic link.

Syntax

followlink file

Description

If the argument is a symbolic link, the command repeatedly applies absreadlink until the result converges, and returns the canonical form of the file to which the link finally points. Otherwise, the command returns the canonical form of the argument.

If a possible infinite loop is detected, the result is the empty string.

Result

The absolute pathname of the final destination of a link.

Status

Only on argument errors

Example

When the user double-clicks with mouse button 2 on an icon which is a symbolic link, it will display the real name of the file it is linked to.

   icon_rules
   {
     * /+
     {
       trigger_action: alt_activate
       {
         realfile=`(followlink $static_arg)
         if == $realfile ''
         then
           yni This icon may be an Infinite Loop!
         else
           for_info This link leads to $realfile
         fi
       }
     }
   }

See also:

absreadlink, which returns the absolute pathname of a link
readlink, which returns the contents of a link

for_info [fyi]

Displays a window presenting information to the user.

Syntax

for_info [-p picture] [-t title] [-b book] [-h topic] text

where:

picture: a picture file to use for the picture
title: text to put in the title bar
book: the help book to be used by the Help button
topic: the help topic to be used by the Help button
text: text displayed in the window

Description

The command allows you to specify a picture to be displayed in the dialog box, and a title for the window. If either book or topic is specified, the dialog box will include a Help button. Choosing Help runs the command:

help topic [-b book]

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following example displays a for_info dialog with the default information icon and the default help book:

   text='The first mouse button has no effect on this icon.'
   for_info -t 'Icon: Compress' -h compress $text

get_attribute [attr]

Gets the text value associated with an object's named attribute.

Syntax

get_attribute [-ddesktop] name object . . .

where:

desktop: desktop whose rules are to be searched
name: the name of the attribute to be searched for
object: the objects to be checked

Description

The rules are searched for an attribute : name clause for each object in turn.

Result

The result is a list containing the body of the clauses for those objects which have an attribute of that name.

Status

The number of objects which do not have an attribute of the specified name.

Example

The following rule defines a comment attribute which is displayed when the icon is double-clicked with mouse button 2:

   icon_rules
   {
     *.comm /F
     {
       attribute: comment=Comment for this icon;
   
       trigger_action: alt_activate
       {
         for_info `(get_attribute comment $static_arg)
       }
     }
   }

get_out [goi]

Adds specified objects to the desktop.

Syntax

get_out -a position [-f desktop] [-d opendesktop] object . . .

where:

position

the position of the first object in one of the following forms, where x and y are numbers:

F: first free position on the grid (default)
Gx,y: position in the standard tidying grid
Px,y: position in pixels
V: The Desktop will pick a position. -a V can be abbreviated to -l.

desktop

specifies a desktop from which the icons will be removed if they are out on it (no default)

opendesktop

the desktop onto which to get out icons (default is main Desktop)

object

the objects to get out

Description

In this form of the command, position specifies the position for the first icon; subsequent icons have position code V, so their position is chosen by the Desktop.

Syntax - position specified for each object

get_out [-f desktop] [-d opendesktop] [object position] . . .

where:

desktop

specifies a desktop from which the icons will be removed if they are out on it (no default)

opendesktop

the desktop onto which to get out icons (default is main Desktop)

position

the position of the icon, in one of the following forms, where x and y are numbers:

F: first free position on the grid (default)
Gx,y: position in the standard tidying grid
Px,y: position in pixels
V: The Desktop will pick a position.

object

the objects to get out

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following example opens the Personal desktop and then gets out the icon for /usr/spool and puts it on the desktop.

   open_desktop Personal.dt
   get_out -l /usr/spool -d Personal.dt

See also:

put_back, which puts icons away

get_resource

Gets resource values as defined in the X resource database.

Syntax

get_resource [-flags] name class

where:

flags

can be one of the following:

a: the Desktop resource name and class are prefixed to the name and class specified, with a separating dot. The resource name and class are those used in fetching all non-widget resources.
r: the Desktop resource name and class, and the ruleset name and class, are prefixed to each name and class specified.

The Desktop resource class is XDesktop3; by default the resource name is xdt3. The ruleset class is Rules; by default the resource name is rules.

name

the name of the resource

class

the class of the resource

Description

The flags must precede the name and class. Both the name and class must have the same number of elements, separated by single dots. The name/class pair is looked up in the Desktop's resource database.

If the resource is found, the result is a single string consisting of the resource value; otherwise it is an empty list.

Status

Only on argument errors.

Example

The following command returns the value of the Desktop's picture directory resource:

   get_resource xdt3.pictureDirectory XDesktop3.PictureDirectory

This can be shortened to:

   get_resource -a pictureDirectory PictureDirectory

Similarly, the following are equivalent:

   get_resource xdt3.rules.loopModules XDesktop3.Rules.LoopModules
   get_resource -r loopModules LoopModules

gti

Displays a prompt and reads user input.

Syntax

gti [-p pic] [-t title] [-d default] [-l length] [-b book] [-h topic] [text]

where:

pic: a picture file to use for the general picture
title: text to be put in the title bar
default: the default text to put in the input area
length: the length of the input area
book: the help book used by the Help button
topic: the topic used by the Help button
text: text to be displayed in the window

Description

This command is used for requesting input from the user. The text and an input area are displayed in a window. If either book or topic are specified, the dialog box will include a Help button. Choosing Help will execute the command:

help topic [-b book]

Result

The text entered by the user, as a single string. This can be substituted into the script using the ```'' operator, as in:

   value=`(gti 'Enter a value:')

Status

The command sets the value of status as follows:

OK (0): the command was successful
CANCELED (2): the command was canceled by the user
ERROR (255): an error occurred

Example

The following script prompts for a filename, and checks that a non-empty name has been entered:

   until
     file=`(gti 'Enter filename:') && != $file ''
   do
     for_info 'Please enter a filename'
   done

See also:

for_info, which displays a text message to the user
yni, which displays a yes/no dialog

help

Requests help display from the Help system.

Syntax

help topic [-b book]

where:

topic: the help topic to be used
book: the help book to be used

Description

The topic and book are passed to the Help system.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following script defines a Help icon that gives help on any icons dropped onto it:

   icon_rules
   {
     Help /F
     {
        trigger_action: d*
        {
          for i
          do
            help $i
            sleep 5
          done
        }
     }
   }

in_text_window [text]

Displays text in a window.

Syntax

in_text_window [-n name] [-t title] [command [args . . .]]

Description

See the shell_window command for details.

join

Joins its arguments into one string.

Syntax

join string . . .

Result

The arguments concatenated, with the prefix, suffix, and separators determined by the variable ofs as follows:

$ofs(1): separator to be inserted between strings. Defaults to a single space if ofs has no elements.
$ofs(2): prefix placed in front of result
$ofs(3): suffix placed after result
$ofs(4): result if list is empty

Status

Only on argument errors.

Example

The following rule clause defines a Debug icon which displays a list of the files dropped onto it. The variable ofs is set to a return character to put each icon filename onto a new line, and ofs(4) is set to the string ``[None]'' to show when an icon has an empty filename:

   icon_rules
   {
     Debug /F
     {
       trigger_action: d*
       {
         ofs=(\n '' '' '[None]')
         for_info `(join 'Icons dropped:' $dynamic_args)
       }
     }
   }

See also:

split, which splits a string into a list of strings

kill

Sends a signal to specified threads or processes.

Syntax

kill [-signal] [thread | process_id] . . .

where:

signal

a name beginning with sig

thread

The name of a thread. If prefixed with ``+'', and the thread is currently waiting for a process to terminate, the signal will also be sent to that process.

If prefixed with ``-'', and the thread is waiting for another thread to terminate, the signal will also be sent to that thread, and so on recursively.

If prefixed with both ``+'' and ``-'', the signal will be sent to those threads implied by the ``-'', and to processes any of these threads are waiting for.

process_id

the number of a process. If prefixed with ``-'', the signal is sent to the process group with the specified number.

Description

The signal is sent to all the specified threads. If it is one of the following special signals, it is also sent to the specified processes:

sigint (default)
sigabrt
sigalrm
sigdetect
sigfpe
sighup
sigill
sigkill
sigpipe
sigquit
sigsegv
sigterm
sigusr1
sigusr2

Status

The number of threads or processes that do not exist. If the signal is not one of the special signals, any specified processes are counted in the value of $status.

Example

The following example starts an xclock in the initial_actions and then kills in the final_actions.

   initial_actions
   {
     xclock &
     xcthread=$last_background_action
   }
   
   final_actions
   {
     kill -sigkill +$xcthread
   }

link_into [lni]

Links files into a directory.

Syntax

link_into dir file . . .

Description

Links files into a directory. Files are not linked if they are already in the specified directory, if there exists a file in the directory with the same basename, or if the directory and file are on different filing systems.

If two or more files with the same basename are specified, it is undefined which is actually linked.

Status

The number of files not linked.

Example

The following command links the file /b/c to /a/c, and the file d/e to /a/d/e:

   link_into /a /b/c d/e

See also:

copy_into, which copies files into a directory
move_into, which moves files into a directory
symlink_into, which symbolically links files into a directory

list count

Returns the number of strings in specified lists.

Syntax

list count [list . . .]

where:

list: a list of strings. The lists must be separated by ``::'' list marks, and can be empty.

Result

A list of the number of strings in each argument.

Status

Only on argument errors.

Example

The following examples illustrate the command for the lists:

x=(a b c)
y=(d e)
z='fghij'

Arguments Result

$x :: $y :: $z (3 2 1)

$x $y :: $z (5 1)

:: $x $y $z :: (0 6 0)

Arguments	Result
$x :: $y :: $z	(3 2 1)
$x $y :: $z	(5 1)
:: $x $y $z ::	(0 6 0)

list intersect

Returns a list of strings occurring in every argument list.

Syntax

list intersect list . . .

Result

A list of the strings that occur in every argument. If any argument is an empty list, the result will be the empty list.

Status

Only on argument errors.

Example

The following example:

   list intersect a b c :: d c b :: b c d e

will return:

   (b c)

See also:

list uniq, which removes duplicates from a list

list sort

Sorts strings in a list.

Syntax

list sort list

Result

The strings in the list sorted into ascending alphabetical order.

Status

Only on argument errors.

Example

The following example:

   x=(One Two Three Four Five Six)
   y=`(list sort $x)
   for_info $y

will display:

   Five Four One Six Three Two

list subtract

Returns a list of strings occurring in the first argument but not the second.

Syntax

list subtract list1 list2

where:

list1: a list of strings to be included
list2: a list of strings to be removed

The lists must be separated by ``::'' list marks.

Result

list1 with any strings occurring in list2 removed.

Status

Only on argument errors.

Example

The following example:

   list subtract (a b a c u s) :: (d c b)

returns:

   (a a u s)

See also:

list intersect, which returns a list of strings occurring in every argument list

list uniq

Removes adjacent duplicate strings from a list.

Syntax

list uniq list

Result

The strings in the list with any adjacent duplicates removed.

Status

Only on argument errors.

Example

The following example:

   x=(M T W T F S S)
   y=`(list uniq $x)
   for_info $y

will display:

   M T W T F S

See also:

list intersect, which returns a list of strings occurring in every argument list

lock_icon

Lock the specified icons permanently on a desktop.

Syntax

lock_icon [-u] -d desktop pathname . . .

where:

desktop: name of the desktop on which to lock the icons
pathname: pathname represented by an icon to lock onto the desktop

Description

The icons for each specified pathname that can be found on desktop are locked on that desktop, or unlocked if the -u flag is specified.

NOTE: The desktop rules are not updated when the desktop is closed. Any icons locked using this command will be unlocked the next time the desktop is opened. This does not affect icons locked using the locked_on_desktop clause within a desktop rule file.

Example

The following example locks the user's home directory on the main Desktop:

   lock_icon -d $XDTUSERHOME/Main.dt $HOME

make_new_file [mkf]

Creates a new file or directory.

Syntax

make_new_file [-flags] dir [-b basename]

where:

flags

can be one of the following:

f: create an empty file (default)
d: create a new directory

dir

the directory for the new file

basename

the basename for the new file. Any leading directory is removed.

Description

A new directory or empty file is created in the named directory. If basename is not specified, the directory must be open, and the user is prompted for a name for the new file or directory. The entered name will be placed in the local variable entered_name.

Status

The command sets the value of status as follows:

OK (0): the command was successful
CANCELED (2): the command was canceled by the user
ERROR (255): an error occurred

Example

The command:

   make_new_file /a -b /c/d

makes a new file /a/d.

See also:

copy_into, which copies a file
duplicate_file, which duplicates a file

mark_changed_directory [mcd]

Highlights the directory changed button if the contents have changed.

Syntax

mark_changed_directory [dir . . .]

where:

dir: the name of a directory, or all open directories if omitted

Description

If any of the specified directories have changed, the directory window is marked by a button which the user can click on to update the directory and remove the mark.

Status

The variable status will hold the number of specified directories that were not open.

Example

The following loop marks any open directories that have changed. It checks every 120 seconds.

   while true
   do
     mark_changed_directory
     sleep 120
   done

menu_actions_of [menu]

Executes a command as if chosen from a menu.

Syntax

menu_actions_of menu item [object . . .] [-d desktop]
[-D directory] [-s staticobj]

where:

menu: the name of the menu
item: the item tag, or a numeric position, in the menu_item clause referenced by menu
object: arguments to be passed to the menu script in $dynamic_args
desktop: a desktop whose rules are to be used in locating the menu
directory: a directory whose rules are to be used in locating the menu
staticobj: object passed to the menu script in $static_arg

Description

Performs the same action as if the user had chosen menu command cmd from menu. The command is executed in a separate thread. The following variables are set:

Variable Value

static_arg the first of static, directory, or desktop to have been specified; otherwise an empty list

dynamic_args the objects, with filenames in canonical form

d_desktop desktop, or an empty list

Variable	Value
static_arg	the first of *static, directory, or desktop* to have been specified; otherwise an empty list
dynamic_args	the objects, with filenames in canonical form
d_desktop	*desktop*, or an empty list

Status

The command sets the value of status as follows:

OK (0): the static argument has an action for that trigger
NOTRIGGER (1): the static argument does not have an action for that trigger

Example

The following rule performs the menu action of item 8 in the directory File menu, if any .bak file receives a menu trigger:

   icon_rules
   {
     *.bak /F
     {
       trigger_actions: menu
       {
         menu_actions_of DirfileMenu 8 $static_arg
       }
     }
   }

See also:

actions_of, which emulates an icon trigger
do_menu_actions_of, which executes the actions synchronously
drop_in_actions_of, which emulates a window background trigger

merge

Merges two or more lists.

Syntax

merge name . . .

Description

The arguments are each taken to be the name of a variable. The result is the first string in each variable, in the order they are named in the arguments, followed by the second string in each variable, and so on until all the variables are exhausted. Each argument is ignored once the end of the contents of the corresponding variable is reached.

Result

The merged lists.

Status

Only on argument errors.

Example

The following example:

   A=(1 2 3 4)
   B=(a b c d e f)
   merge A B

will return:

   1 a 2 b 3 c 4 d e f

See also:

join, which joins the strings in a list
split, which splits a string into a list

move_into [mvi]

Moves files into a directory.

Syntax

move_into dir file . . .

Description

Moves the files into the specified directory. Files are not moved if they are already in that directory, or if there exists a file in the directory with the same basename. Files might not be moved if the directory and file are on different filing systems. If two or more files with the same basename are specified, it is undefined which is actually moved.

Status

The number of files not moved.

Example

The following example gives the default rule for the trigger move:

   trigger_action: move
   {
     move_into $dynamic_args $static_arg
   }

See also:

copy_into, which copies files into a directory
link_into, which links files into a directory
symlink_into, which symbolically links files into a directory

open_desktop [odt]

Opens or redisplays a window showing the contents of a desktop.

Syntax

open_desktop [-flags] [-f format] [desktop [desktop2]]

where:

flags

can be one of the following:

F: leave format unchanged, rather than reverting to default. The format parameter must not be specified.
h: hide the window of the desktop
i: display icons
n: display names and formatted information
m: make desktop and desktop2 the main Desktop (see below)
M: make desktop2 the main Desktop if desktop was previously
r: reread the contents of the desktop(s), without saving them first
R: do not save the desktop contents when the desktop is closed. This state is retained until the desktop is closed, or reloaded.
N: do not save contents of desktop (2 arguments only)

format

see below

desktop

see below

desktop2

see below

Description

When names are being displayed, with the -n option, the text displayed consists of the format string with the following ``%'' character sequences replaced with information about the pathname (file or directory), as shown in the following list:

%B: basename of the object
%C: class of the object
%I: title of the object that would be used in icon mode
%P: absolute pathname of the object
%R: name of the object relative to the user's $HOME directory
%S: size of the file, in bytes
%T: time the file was last changed
%%: a percent character

A separate format is remembered for each open desktop window. Whenever the n flag is specified without a format, the format %R is used. The following options are available:

Option Description

No desktops specified The h, m, M, and N flags are ignored. If the r flag is specified, all open desktop windows are reloaded from their rule files, losing the current contents and rules.
If the i and n flags and the -f format are specified, all open desktop windows are redisplayed in this format.

One desktop specified If no window is open for desktop, a window is opened for it, and the r flag is ignored.
If a window is open for desktop, the r flag causes it to be reloaded from its rule file, losing the current contents and rules.
In either case, the m flag causes it to become the main Desktop. The h flag causes the window to be hidden (otherwise it is visible to the user). The M and N flags are ignored.
If the i and n flags and the -f format are specified, this desktop is redisplayed in this format.

Two desktops specified If no window is open for desktop, this command has no effect. Otherwise, any existing window for desktop2 is closed and its contents are redisplayed in the window for desktop.
The flags have the following actions:

m
desktop2 becomes the main Desktop

M
desktop2 becomes the main Desktop only if desktop was the main Desktop

h
the window is hidden (otherwise it will be visible to the user)

N
the contents of desktop are not saved (by default, they are)

r
desktop2 is reloaded from its rule file, losing the current contents and rules. No initial_actions or final_actions clauses are executed as a result of the reload.
If the i and n flags and -f format are specified, the desktop is redisplayed in this format.
The final_actions clause for desktop will be executed, and if desktop2 is not already open, its initial_actions will be executed.

Option	Description
No desktops specified	The h, m, M, and N flags are ignored. If the r flag is specified, all open desktop windows are reloaded from their rule files, losing the current contents and rules. If the i and n flags and the -f *format* are specified, all open desktop windows are redisplayed in this format.
One desktop specified	If no window is open for *desktop, a window is opened for it, and the r flag is ignored. If a window is open for desktop, the r flag causes it to be reloaded from its rule file, losing the current contents and rules. In either case, the m flag causes it to become the main Desktop. The h flag causes the window to be hidden (otherwise it is visible to the user). The M and N flags are ignored. If the i and n flags and the -f format* are specified, this desktop is redisplayed in this format.
Two desktops specified	If no window is open for *desktop, this command has no effect. Otherwise, any existing window for desktop2* is closed and its contents are redisplayed in the window for *desktop. The flags have the following actions: m desktop2* becomes the main Desktop M *desktop2* becomes the main Desktop only if *desktop* was the main Desktop h the window is hidden (otherwise it will be visible to the user) N the contents of *desktop* are not saved (by default, they are) r *desktop2* is reloaded from its rule file, losing the current contents and rules. No initial_actions or final_actions clauses are executed as a result of the reload. If the i and n flags and -f *format* are specified, the desktop is redisplayed in this format. The final_actions clause for *desktop* will be executed, and if *desktop2* is not already open, its initial_actions will be executed.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following example opens the desktop Invoices.dt:

   open_desktop Invoices.dt

See also:

display_directory, which opens a directory window

pixmap_check [pxc]

Updates icons if specified picture files have changed.

Syntax

pixmap_check [picture . . .]

where:

picture: picture files to check. If no arguments are specified, this is equivalent to specifying all the pictures used so far.

Description

The named pictures are checked to see if they have changed. If they have, the information held about those pictures is updated, and all icons using those pictures have their picture changed.

A picture has changed if either the search mechanism would yield a different picture file, or the mechanism would yield the same picture file, but the contents of that file have changed.

Status

The number of pictures not used so far by this Desktop session.

Example

The following rule edits a .px file with the icon editor if it is activated, and then updates its icon to reflect the changes:

   icon_rules
   {
     *.px /FW
     {
        trigger_action: activate
        {
          pixed $static_arg
          pixmap_check $static_arg
        }
     }
   }

See also:

check, which checks and updates icons

popup

Displays a popup menu, at the position of the mouse cursor, in a directory or desktop window.

Syntax

popup menuname [args . . .]

where:

menuname: name of the menu, as defined in the menu command
args: an optional set of arguments which will be passed as the dynamic arguments of the action when a menu item is selected

Description

A popup menu will only be displayed for as long as the mouse button is pressed.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following clause pops up an icon menu when the user holds mouse button 3 on the Trash icon:

   icon_rules
   {
      trash.dt /FNWM
      {
        picture=waste_e_c.px;
        title=Trash;
        
        trigger_action: menu
        {
          popup TrashCanMenu
        }
      }
   }

put_back [pbi]

Removes icons from a desktop.

Syntax

put_back object . . . [-d opendesktop]

where:

object: objects to be put back
opendesktop: the desktop from which to put back icons

Description

Removes the icons of the named objects from the named desktop. Locked icons are not removed.

Status

The number of icons that are locked or not present on the specified desktop.

Example

The following example takes a /tmp icon from the main Desktop:

   put_back /tmp -d Main.dt

pwd

Returns the current directory for the current thread in canonical form.

Syntax

pwd

Result

The current directory of the thread in canonical form.

Status

Only on argument errors.

Example

The following example checks the present working directory against a list of safe directories, and if a match is not found, it does a cd to the first one:

   if ! match `pwd $safe_dirs
   then cd $safe_dirs(1)
   fi

query all_triggers

Returns a list of triggers.

Syntax

query all_triggers

Result

A list containing one string for each trigger appearing in the trigger table.

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>= 768): an argument error occurred

Example

The following example displays the available triggers when a Query icon is activated:

   icon_rules
   {
     Query /F
     {
       trigger_action: activate
       {
         trigs=`( query all_triggers )
         for_info 'The triggers available are' $trigs
       }
     }
   }

query contents

Returns a list of the contents of a specified directory.

Syntax

query contents [-flags] [window] . . .

where:

flags

can be one of the following:

b: return only the basename of each object
d: read directories from disk rather than examining the window. Entries are not generated for the ``.'' or ``..'' directories.

window

an open desktop or directory window, which may be hidden

Result

A list of the contents of the specified windows.

Status

The number of windows named that were not open. If the d flag is specified, only desktop windows are counted.

Example

The following example determines whether a directory is empty by counting the number of elements in the directory:

   if -eq 0 `(list count `(query contents -d $directory))
   then empty=true
   else empty=false
   fi

query main_desktop

Returns the name of the main Desktop.

Syntax

query main_desktop

Result

The canonical name of the main Desktop if there is one, or an empty list if not.

Status

Only on argument errors.

Example

This is used to find the name of the main Desktop, if there is one.

   maindt=`(query main_desktop)

See also:

query open_desktops, which returns the names of all open desktops

query max_gridsize

Returns a list of the grid sizes of specified desktops or directories.

Syntax

query max_gridsize { window } . . .

Result

A list of the grid sizes of each desktop or directory window, in the form:

x,y

This specifies the bottom-right grid position within the window (position ``0,0'' is at the top-left).

NOTE: No value is returned if the specified window is not open.

Status

The variable status will hold the number of windows named that were not open.

Example

The following example, if placed within a desktop rule file, will cause all icons double-clicked with the alternate mouse button to move to the bottom-right grid position on that desktop.

   icon_rules
   {
      *
      {
         trigger_action: alt_activate     
         {
            get_out -a G`(query max_gridsize $s_desktop) -d $s_desktop $static_arg  
         }
      }
   }

query open_desktops

Returns the names of all open desktops.

Syntax

query open_desktops

Result

A list of strings giving the canonical names of all open desktops, whether visible or not.

Status

Only on argument errors.

Example

The following example puts the names of all open desktops into the variable numodt. $#num_odt is the number of items in the variable.

   num_odt=`{ query open_desktops }
   for_info 'You  have' $#num_odt 'Desktops open'

See also:

query main_desktop, which returns the name of the main Desktop
query open_directories, which returns the names of all open directories
query open_treeviews, which returns the names of all open treeviews

query open_directories

Returns the names of all open directories.

Syntax

query open_directories

Result

A list of strings giving the canonical names of all open directories.

Status

Only on argument errors.

Example

This returns the names of any open directories:

   opendir=`(query open_directories)

See also:

query main_desktop, which returns the name of the main Desktop
query open_desktops, which returns the names of all open desktops
query open_treeviews, which returns the names of all open treeviews

query open_treeviews

Returns the names of all open tree views.

Syntax

query open_treeviews

Result

A list of strings giving the canonical names of all open tree views.

Status

Only on argument errors.

Example

The following example puts the names of any open tree views into the variable numtree:

   open_trees=`{ query open_treeviews }
   for_info 'You have the following tree views open:' $open_trees

See also:

query main_desktop, which returns the name of the main Desktop
query open_desktops, which returns the names of all open desktops
query open_directories, which returns the names of all open directories

query picture

Returns a list of the picture filenames used for specified objects.

Syntax

query picture [-d desktop] [object . . .]

where:

desktop: use the rules of the specified desktop
object: the objects to be queried

Result

A list of the filenames of the pictures used for the icons, as specified in the rule files. If there is no picture, an empty string is returned.

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>= 768): an argument error occurred

Example

The following example returns the name (as given in the rules) of the pixmap file for $HOME on the main Desktop:

   query picture -d Main.dt $HOME

See also:

query pixmap, which returns the actual pictures used for icons

query pixmap

Returns a list of the pixmaps used for specified objects, with one string for each argument.

Syntax

query pixmap [-d desktop] [object . . .]

where:

desktop: use the rules of the specified desktop
object: the objects to be queried

Result

The format of each returned string is:

A Ppixmap Mmask Ccolormap Wwidth Hheight

where the components are as follows:

pixmap: the pixmap id for the picture, in hexadecimal
mask: the pixmap-id for the mask, in hexadecimal (omitted if there is no mask)
colormap: the colormap id, in hexadecimal
width: the width in decimal
height: the height in decimal

If there is no picture, all ids are zero.

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>- 768): an argument error occurred

Example

The following example returns details of the $HOME pixmap in the format described:

   query pixmap -d $XDTUSERHOME/Main.dt $HOME

For example:

   A P1200fe M1200ff C600d8 W64 H48

See also:

query picture, which returns the names of pictures used for icons

query selections

Returns a list of icons which have been selected.

Syntax

query selections [flags] [directory | desktop] . . .

where:

flags: can be b, which returns only the basename of each object
directory: the name of a directory
desktop: the name of a desktop rule file

Result

A list of strings, one for each selected icon. Each string is the canonical pathname represented by the icon, unless the -b flag is specified, in which case it is the basename of the icon's underlying pathname. If arguments are specified, only selected icons visible in the specified windows are returned.

Status

The number of desktop or directory windows specified that were not open.

Example

The following example defines a menu command, called 'diff'erences, that checks how many icons have been selected:

   menu_item: 'diff'erences
   {
      sels=`(query selections $static_arg)
      if -ne $#sels 2
      then
        for_info You must only select TWO icons!
      else
        shell -n Diff 'diff $dynamic_args | more ; xdtwait'
      fi
   }

See also:

query contents, which returns a list of all the pathnames represented by icons in a desktop or directory window

query size

Returns a list of the sizes of specified objects.

Syntax

query size [-d desktop] [object . . .]

Result

A list of the sizes of the objects, in bytes. This may not be meaningful for objects that are not regular files.

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>- 768): an argument error occurred

Example

The following example returns the size, in bytes, of myfile:

   query size $HOME/myfile

query thread_info

Returns information about threads.

Syntax

query thread_info [-flags] . . . [thread] . . .

where:

flags

return a string depending on the thread or type, as follows:

t: thread type
i: thread information
s: thread's state; one of active, waiting, or suspended
p: if the thread is waiting for a process, the number of the process. If the thread is waiting for a pipeline, a string consisting of a vertical bar, space, and the number of threads in the pipeline which are still executing. Otherwise an empty string.
P: the name of the thread's parent. Even if it is not still in existence it will not be reused.

thread

the thread to be queried

Description

The information available depends on the thread type, according to the following table. A blank entry means that the result is unspecified:

Type -t flag -i flag

System system

Desktop desktop Desktop pathname

Directory directory Directory pathname

Treeview treeview Directory pathname

Menu enable_if enable

XQP request xqp Request script

Pipeline element pipeline Position in pipeline

Other

Type	-t flag	-i flag
System	system
Desktop	desktop	Desktop pathname
Directory	directory	Directory pathname
Treeview	treeview	Directory pathname
Menu	enable_if	enable
XQP request	xqp	Request script
Pipeline element	pipeline	Position in pipeline
Other

Result

A list, containing one element per flag specified per thread specified, with the information for a given thread in consecutive elements, in the order of the flags specified (so that -pt and -tp cause different results), and the information for the various threads in the order the threads are specified.

Example

In the following example, $thread_name(1) is the name of the current thread, so the query thread_info command puts the name of the parent thread into the variable daddy:

   daddy=`( query thread_info -P $thread_name(1) )
   for_info 'Parent Thread is' $daddy

query title

Returns a list of the titles of specified objects.

Syntax

query title [-d desktop] [object . . .]

where:

desktop: use the rules of the specified desktop
object: the objects to be queried

Result

A list of the titles used for the objects.

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>- 768): an argument error occurred

Example

The following example returns the title of this file on the main Desktop; e.g., /u/claudio/MyDir/myfile will have a title of MyDir/myfile:

   query title -d $XDTUSERHOME/Main.dt $HOME/MyDir/myfile

query version

Returns the version of the Desktop.

Syntax

query version

Result

The version of the Desktop that is currently running.

Status

Only on argument errors.

Example

The following example displays the version of the Desktop:

   for_info This is X.desktop `(query version)

query visibility

Returns a list of desktop and directory windows in which a specified icon is visible.

Syntax

query visibility [object . . .]

Result

A list of the names of all the open desktops and directories that contain object. If more than one object is specified, the resulting names are joined together into one list.

A window containing object will be included if it is hidden, or object is not currently visible, but not if the icon is suppressed using a null picture.

NOTE: If there is more than one argument, the same directory or desktop could appear more than once in the result.

Example

In the following example, query visibility returns the names of all desktops and directories that currently display an icon for $HOME, i.e., where $HOME is visible:

   vis=`( query visibility $HOME 0

read

Reads one record from standard input.

Syntax

read [-flags] [-r terminator]

where:

flags

can be one of the following:

n: causes the whole record to be returned as a single string, i.e., ignores $ifs.
a: causes the read command to continue reading until end of file, generating one record

terminator

normally a record is one line, but if a terminator is specified, then a record is terminated when this terminator occurs on a line on its own, possibly followed by white-space. A newline in a terminator has an unspecified effect.

Description

The command reads one record from standard input and divides it into words using $ifs(1) in the normal way; the result of the command is the resulting list. The result excludes the terminating newline and the terminator.

Status

The command sets the value of status as follows:

YES (0): a record was read
NO (1): no record was read because end-of-file has already been reached on standard input
ERROR (255): an error occurred

Example

The following example defines a List Users icon which displays a list of users:

   initial_actions
   {
      function list_users  
      {
         ifs=':"
         while record=`read    
         do
            users=$users\n$record(1)
         done
         for_info $users
      }
   }
   icon_rules
   {
      listusers /FX
      {
         title=List Users;     
         trigger_action: activate
         {
            list_users < /etc/passwd
         }
      }
   }

readlink

Returns the contents of a symbolic link.

Syntax

readlink pathname . . .

Result

If the argument is a symbolic link, the result is the uninterpreted contents of the link. Otherwise, it is the canonical form of the argument.

Status

Only on argument errors.

Example

The following example edits an activated icon unless it is a symbolic link:

   icon_rules
   {
     * /FW
     {
       trigger_action: activate
       {
         slink=`( readlink $static_arg )
         if == $slink $static_arg
         then
           actions_of edit $static_arg
         else
           for_info Symbolic link to $slink
         fi
       }
     }
   }

relativepath

Returns the pathname relative to the user's home directory.

Syntax

relativepath pathname . . .

Result

The argument is first converted to canonical form. If the result starts with the value of the string $home(1)/, then that string is stripped off to find the result. Otherwise, the result is the canonical form of the argument.

Status

Only on argument errors.

Example

For example:

relativepath /u/claudio/MyDir/myfile

will return MyDir/myfile if $home is /u/claudio.

Whereas, this example:

relativepath /usr/lib/X11

will return /usr/lib/X11.

See also:

basename, which returns the basename
canonical, which converts its arguments to canonical form
dirname, which returns the directory name
extension, which returns the extension

remove [rmi]

Removes files from the filing system.

Syntax

remove file . . .

Description

The named files and their icons are removed from the filing system. Directories cannot be removed with this command. Any open directory windows containing deleted icons will be updated if they are open.

Status

The number of files not removed.

Example

The following rule defines a Shredder icon that permanently deletes files dropped onto it without a warning:

   icon_rules
   {
     shredder /F
     {
       picture=shredder.px;
       title=Shredder;
   
       trigger_action: d*
       {
         remove $dynamic_args
       }
     }
   }

remove_dynamic_rule [rdr]

Removes a dynamic rule.

Syntax

remove_dynamic_rule [-flags] name . . .

where:

flags: can be x, which executes the final clause, if present
name: the name of the dynamic rule

Description

All dynamic rules associated with each name are removed. Any final_actions clause will only be executed if the -x flag is provided.

Status

The variable status will hold the number of names which have no associated dynamic rules.

Example

The following example removes a dynamic rule called myrule. This rule would have previously been set up using dynamic_rule:

   remove_dynamic_rule myrule

See also:

dynamic_rule, which installs a dynamic rule

rename

Renames a file.

Syntax

rename file [-b basename] [-d opendesktop]

where:

file: the file to be renamed
basename: the new basename for the file. Any leading directory is removed.
opendesktop: the desktop for the rename

Description

The basename of the specified, file or directory is changed. If basename is not specified then the user is prompted for a name for the duplicate, and the entered name is placed in the local variable $entered_name. In this case, the icon used will be in the specified desktop, or the directory of the file (which must be open and not hidden) if none is specified.

The directory window containing the new icon will be updated if it is open.

Status

The command sets the value of status as follows:

OK (0): the command was successful
CANCELED (2): the command was canceled by the user
ERROR (255): an error occurred

Example

The following command defines a Rename function:

menu_item: Rename... _R_Ctrl<Key>R_Ctrl+R { if -eq $#dynamic_args 0 then for_info -h select 'You must select an icon.' exit fi

for icon in $dynamic_args do rename $icon done }

For simplicity, this script omits the standard checking that usually makes sure that the icons may be renamed.

reorganize_desktop [tds]

Reorganizes specified desktops.

Syntax

reorganize_desktop [opendesktop . . .]

where:

opendesktop: desktops to be reorganized, which must be open. If omitted, all open desktops are affected.

Description

Each icon is moved to a unique visible grid position so that the earliest grid positions in each desktop are all filled and no icons overlap. This is equivalent to putting back all the icons in each desktop, and then getting them all out with position code F.

Status

The number of desktops named that were not open.

Example

The following example shows how a simplified desktop View menu could use the reorganize_desktop command to provide a Reorganize menu option:

   menu: DesktopViewMenu
   {
     menu_item: Clean up     _l_Ctrl<Key>L_Ctrl+L
       { tidy_desktop $static_arg }
     menu_item: Reorganize   _R_Ctrl<Key>R_Ctrl+R
       { reorganize_desktop $static_arg }
   }

See also:

tidy_desktop, which moves icons to the nearest grid position

report_status [report]

Displays a status report dialog box.

Syntax

report [-flags] [-p pic] [-t title] [-c canceltext | -C cancelpic]
[-b book] [-h topic] [text]

where:

flags: can be a, which closes the dialog box automatically when the thread exits. Otherwise the dialog box stays until closed.
pic: the picture file to use for the general picture
title: the text to put in the title bar
canceltext: the text for the Cancel button
cancelpic: the picture for the Cancel button
book: the help book to be used by the Help button
topic: the topic to be used by the Help button
text: the text to be displayed

Description

This command is special in that repeated use in a single Deskshell thread is different from use in several threads. This description thus applies to a single thread. The use of this command in one thread cannot affect its use in other threads.

Each Deskshell thread has a single report window, which may be closed, open, or canceled. When a thread is created, the window is initially closed. It is opened and closed by report_status, and canceled by the user pressing the Cancel button (the window disappears when it is canceled).

The effect of the command depends both on the state of the window and on whether a text argument is provided, as shown in the following table:

Text Window

provided state Effect

no any The window is closed.

yes closed The window is opened, with the text and pictures specified by the arguments.

yes opened The text and picture in the window are changed to those specified by the arguments.

yes canceled The window remains invisible, but its state is altered.

If the thread terminates while the window is still open, it remains there until canceled by the user. However, if the last use of the command in the thread specified the a flag, the window closes automatically when the thread terminates (this flag is set or reset on each use of the command).

Text	Window
provided	state	Effect
no	any	The window is closed.
yes	closed	The window is opened, with the text and pictures specified by the arguments.
yes	opened	The text and picture in the window are changed to those specified by the arguments.
yes	canceled	The window remains invisible, but its state is altered.

If either book or topic is specified, the dialog box will include a Help button. Choosing this button will run the command:

help topic [-b book]

Status

The command sets the value of status as follows:

WASCLOSED (0): the window was previously closed
WASOPEN (1): the window was previously open
CANCELED (2): the window was previously canceled
ERROR (255): an error occurred

Example

The following example displays a progress report which allows a copying operation to be canceled by the user:

   for i in *
   do
     report -a $i 'file copied'
     if -eq $status 2
     then break
     fi
     # loop body
   done

reset

Resets the Desktop.

Syntax

reset [options]

where:

options

can be one of the following:

do_die: termination state is entered, as described for the die command. When the process would have exited, it re-executes instead.
new_env: a new environment is constructed before the re-execute. This contains all the global variables, but not the local variables of the system thread.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following example gives the rule for the Restart.obj in the Admin toolshed window:

   if yni -t Restart 'Restart X.desktop'
   then
     reset
   fi

resource_line [irl]

Modifies the Desktop resource database.

Syntax

resource_line string . . .

Description

The arguments are catenated together, separated by single spaces. The resulting string is added to the resource database used by the Desktop. If a parsing error occurs, it is undefined whether the line has been installed.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following example sets the Desktop to fill the Root window by setting the appropriate resource:

   trigger_action: activate
   {
     if yni 'Do you want to make your Personal desktop''s background blue'
     then
       resource_line 'XDesktop3.Personaldt.desktop.back.background: blue'
     fi
   }

select [sel]

Selects or unselects specified objects.

Syntax

select [-flags] [object . . .]

where:

flags

can be one of the following:

s: select, canceling all existing selections. This is the default if -D is not specified.
a: add to selection list. This is the default if -D is specified.
t: toggle selection state
u: unselect

Together with any of the following:

A: add all the icons in all the open desktops to the selection list. Applies after any other change.
D: each object should be a directory or open desktop. The command is applied to each icon in those directories or desktops.
U: cancel all existing selections. Applies before any other change.

object

the objects to be affected

Description

The selection state for the icons of the named objects if altered according to the flags. The titles of those icons selected will be highlighted.

An icon will only be selected if it is on an open desktop or directory window. If an icon is removed from a desktop, it will be unselected if it is not in any other open window. If a desktop or directory window is closed, any selected icons which are no longer visible in any desktop or directory window are unselected.

Status

The number of objects named that are not visible or open for the D flag.

Example

The following command defines a simplified Edit menu with Select All and Deselect All functions:

   menu_item: Select All       _S_Ctrl<Key>/_Ctrl+/
     { select -D $static_arg }
   menu_item: Deselect All     _D_Ctrl<Key>\_Ctrl+\
     { select -U }

sequence

Returns a list of numbers specified by the arguments.

Syntax

sequence first [step] [flag] limit

sequence [ [flags] limit]

where:

first

initial value; defaults to ``1''

step

increment value. If zero, or omitted, it defaults to ``1'', or ``-1'' if flag is ``>''.

flags

can be one of the following:

->: the first number is first, and subsequent numbers differ by step (default)
*: the list will contain exactly limit numbers
<: the sequence is ascending
>: the sequence is descending

These flags need to be quoted.

limit

the limit. Defaults to ``1''.

Description

The sequence command is used to generate numbers for counted loops.

Result

The result is a list of numbers (converted to strings). The first number is first, and subsequent numbers differ by step if flag is ``->'' or omitted. All elements of the list are less (greater if step is negative) than or equal to last. If flag is ``*'', then the list contains exactly limit numbers.

It is possible for the list to contain no elements.

Status

Only on argument errors.

Example

The following shows sequences generated by different arguments:

Command Result

sequence 1

sequence 1 6 1 2 3 4 5 6

sequence 6 1

sequence 6 > 1 6 5 4 3 2 1

sequence 4 * 3 4 5 6

sequence 1 2 6 1 3 5

Command	Result
sequence	1
sequence 1 6	1 2 3 4 5 6
sequence 6 1
sequence 6 > 1	6 5 4 3 2 1
sequence 4 * 3	4 5 6
sequence 1 2 6	1 3 5

shell_window [sh] [shell]

Executes a shell in a window.

Syntax

shell_window [-n name] [-t title] [command [args . . .] ]

where:

name: the name of the window
title: the title of the window
command: the command to be executed
args: arguments

Option analysis

This command does not undergo option analysis. For each parameter word beginning with a dash, that and the next parameter word are removed, and remaining parameters then constitute the command.

Description

If a command is specified, then it is executed in a text window (the command used to do this is specified by resources). If no command is specified, then an interactive shell, specified by resources, is used.

Status

The command sets the value of status as follows:

OK (0): the command was successful
ERROR (255): an error occurred

Example

The following shell_window command will open an xterm with the title ``My Icon'' and will run the program myprog in that xterm window:

   icon_rules
   {
     myicon /FX
     {
       trigger_action: activate
       {
         shell_window -t 'My Icon' myprog
       }
     }
   }

show_greeting [rgw]

Redisplays the Desktop greeting window.

Syntax

show_greeting

Description

The Desktop greeting window is reopened, showing the version number of the Desktop.

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>= 768): an argument error occurred

Example

The following script displays the greeting window:

   initial_actions
   {
     show_greeting
   }

sleep

Suspend current command.

Syntax

sleep seconds [milliseconds]

where:

seconds: the length of time to sleep
milliseconds: optional time, in milliseconds, added to seconds. This value may be greater than ``999''.

Description

The current thread is suspended for the specified length of time. Note that there may also be an additional delay until it is rescheduled.

Status

Only on argument errors.

Example

The following command sleeps for 1.5 seconds:

   sleep 1 500

It is equivalent to:

   sleep 0 1500

source

Executes commands from a file.

Syntax

source file [argument . . .]

where:

file: the name of the file containing commands
argument: an optional list of arguments that is passed to the command in $*

Status

As set by the command(s) executed from file.

Example

If the file demo contains:

   var=$var^$*

then the command:

   var='The result is '
   source demo 'two'

sets var to:

   'The result is two'

split

Splits a string into a list of strings.

Syntax

split string . . .

Description

Each argument is split at those characters which occur in the value of the first string in the variable ifs.

If this variable holds no strings, then each argument is split at the three white space characters: space, tab, and newline. If the first string is ``'''', it splits after every character. All empty strings are discarded. The result is the list of the remaining strings.

Result

The list of strings.

Status

Only on argument errors.

Example

The following function splits its argument into a list of the component directory names:

   function split_path
   { ifs='/' return `( split $* ) ]

See also:

join, which joins a list into a string
merge, which merges several lists

symlink_into [sli]

Symbolically links files into a directory.

Syntax

symlink_into dir file . . .

Description

The named files are symbolically linked into the named directory. Files are not linked if they are already in that directory, or if a file with the same basename already exists in the directory. If two or more files with the same basename are specified, it is undefined which is actually linked.

The new symbolic links contain the exact file argument converted to an absolute or relative pathname.

Status

The number of files not linked.

Example

For example:

   symlink_into /a /b/c /d/e ../g/h

creates the following links:

/a/c --> /b/c
/a/e --> /d/e
/a/g --> ../g/h, i.e., g/h in this case

If you move /a/g to /x/y/z/w it then points to /x/y/z../g/h which is /x/y/g/h.

See also:

copy_into, which copies files into a directory
link_into, which links files into a directory
move_into, which moves files into a directory

tidy_desktop [tdg]

Tidies icons on specified desktops.

Syntax

tidy_desktop [desktop . . .]

Description

Icons in desktop are moved to the closest unique grid positions.

Status

The number of desktops specified that were not open.

Example

The following command defined a simplified desktop View menu:

   menu: DesktopViewMenu
   {
     menu_item: Clean up       _l_Ctrl<Key>L_Ctrl+L
       { tidy_desktop $static_arg }
     menu_item: Reorganize     _R_Ctrl<Key>R_Ctrl_R
       { reorganize_desktop $static_arg }
   }

See also:

reorganize_desktop, which moves icons to the earliest grid positions on a desktop

tolower

Converts its arguments to lower case.

Syntax

tolower string . . .

Result

A list of the arguments, with each character converted to lower case.

Status

Only on argument errors.

Example

For example:

   tolower 'Monday 12th May'

will return ``monday 12th may''.

See also:

toupper, which converts its argument to upper case

toupper

Converts its arguments to upper case.

Syntax

toupper string . . .

Result

A list of the arguments, with each character converted to upper case.

Status

Only on argument errors.

Example

The following example converts the user's name to upper case:

   name=`(gti 'What is your name?')
   name=`(toupper $name)

See also:

tolower, which converts its arguments to lower case

true

Tests whether all its arguments are true.

Syntax

true [word. . .]

where:

word: the argument, which is converted to a number

Status

The command sets the value of status as follows:

YES (0): all arguments are zero (true), or there are no arguments
NO (1): at least one argument is non-zero (false)

Example

The following example display a dialog box if all elements of $list are zero:

   if true $list
   then
     for_info 'All zero'
   fi

See also:

false, which tests whether any argument is false

unextended

Removes the extension of its argument.

Syntax

unextended pathname . . .

Result

The argument converted to canonical form, with the part after the last dot in its basename removed. Because unextended first converts its argument to canonical form, the following command:

   `( basename `( unextended $file ))

is different from:

   `( unextended `( basename $file ))

For example, if $HOME is /a/b, a file /a/b/c/d.ext will return the following values:

Command Value returned

$home /a/b

$file /a/b/c/d.ext

basename $file d.ext

unextended $file /a/b/c/d

unextended `(basename $file) /a/b/d

basename `(unextended $file) d

Command	Value returned
$home	/a/b
$file	/a/b/c/d.ext
basename $file	d.ext
unextended $file	/a/b/c/d
unextended `(basename $file)	/a/b/d
basename `(unextended $file)	d

Status

Only on argument errors.

Example

The following icon_rules clause makes files with a .Z suffix uncompress when double-clicked:

   icon_rules
   {
     *.Z /FW
     {
       picture=compressed.px;
   
       trigger_action: activate
       {
         uncompress $static_arg
         check -R $static_arg `( unextended $static_arg )
       }
     }
   }

The uncompress command converts file.Z to file, the uncompressed version. The check command then removes the old compressed file icon, $static_arg, and displays the uncompressed file icon, unextended $static_arg.

See also:

extension, which returns the extension of its argument

variables

Returns the contents of each of its arguments.

Syntax

variables name . . .

Description

The arguments are each taken to be the name of a variable.

Result

The result is the strings in the variables, in the order in which they are named in the arguments.

Status

Only on argument errors.

Example

The command:

   variables status HOME USER MAILER

returns the contents of $status, $HOME, $USER, and$MAILER.

variation_class [vclass]

Changes the variation class.

Syntax

variation_class class object . . .

Description

The variation class of the named objects will be changed to class, which must be a single digit. The icons for these objects will not be automatically updated.

The following variation classes are used by the Desktop to represent the state of the objects:

0: closed/inactive state (default)
1: open/active state
2: hidden (cannot be seen in desktop or directory windows)
3: in use (for example, a file is being edited)
4: trashed

Status

The command sets the value of status as follows:

OK (0): the command was successful
Special (>= 768): an argument error occurred

Example

The following script sets the variation class to ``1'', executes a script, and then sets the variation class back to ``0''.

If the icon picture is different for the object when its variation class is ``1'', then the picture changes before the script is executed, changing back when the variation class is set back to ``0''.

   trigger_action: activate
   {
     variation_class 1 $static_arg
     check $static_arg
     script
     variation_class 0 $static_arg
     check $static_arg
   }

The following icon rules give different icons to the two variation classes:

   {
     myfile /F0 %// denotes vclass 0
     {
       picture=file.px;
     }
     myfile /F1 %// denotes vclass 1
     {
       picture=wizard.px;
     }
   }

yni

Displays a yes/no dialog box.

Syntax

yni [-p pic] [-t title] [-y texty | -Y picy] [-n textn | -N picn]
[-b book] [-h topic] [text]

where:

pic: the picture file to use for a general picture
title: text to put in the title bar
texty, textn: the text for the Yes and No buttons
picy, picn: the pictures for the Yes and No buttons
book: the help book used by the Help button
topic: the help topic used by the Help button
text: the text to be displayed in the dialog box

Description

Two buttons and the text are displayed in a window. If either book or topic are specified, the dialog box will also include a Help button. If the user chooses this, the following command is executed:

help topic [-b book]

Status

The command sets the value of status as follows:

YES (0): the Yes button was pressed
NO (1): the No button was pressed
CANCELED (2): an error occurred

Example

For example:

   if
     text='Are you sure you want to exit X.desktop?'
     yni -t Exit -h Exit -Y desktop_c.px -N desktop_o.px $text
   then
     die -i
   fi