xdt3(XC)

xdt3 -- the graphical user interface for the Desktop

Command syntax

xdt3 [Xt_options]

Description

xdt3 is the X client that determines the behavior and appearance of the Desktop. xdt3, also referred to as the Desktop, provides a graphical user interface for executing utilities and applications, moving through directories, and manipulating files.

Icons are used to represent utilities, applications, files, and directories on the Desktop. The Desktop can be used to attach icons to files and to define the behavior generated by manipulating those icons with the mouse. For example, you can open windows for files and directories or run programs and utilities by doubling-clicking on their corresponding icons.

Desktop-specific features such as icons, menus, and mouse actions are primarily defined in Desktop objects and rules within rule files. The Desktop resource file also affects elements of the behavior and appearance of the Desktop. This manual page includes sections on objects, rules, rule files, and important Desktop resources.

Command options

xdt3 supports all of the standard Xt_options(XC), except the -iconic option.

Objects

Objects are used for linking mouse actions or ``triggers'' to system or Desktop actions and tasks. A single object, represented by a user-selected icon, can have different scripts to interact with a binary in different ways; objects are consequently useful for implementing applications on the Desktop.

Some advantages of objects are that they are self-contained, well-suited for portability, easily exchanged from user to user, simply structured and easy to debug.

An object is a directory that contains several specific files but behaves as if it is a single entity with its own icon. These files determine the various properties of the object, including the picture used for the object icon, and the specific actions that are executed when the object is manipulated.

The main guidelines associated with objects are:

An object directory is created with the desired name of the object, followed by the extension ``.obj''.
The icon for the object is placed in the object directory with the filename picture.px. A pixmap, also called a picture file, is used to generate the icon.
System or Desktop actions can be defined to correspond with each required manipulation of the object (clicking, dragging and dropping, and so forth).
A sequence of mouse actions and optional keystrokes is referred to as a trigger or trigger action. For information on defining triggers, see ``Trigger descriptions'' and the Graphical Environment Guide.

For example, you could define an object with the title ``Compress'' in a directory named Compress.obj. The icon for the object ``Compress'' is then stored in Compress.obj/picture.px.

In the object script Compress.obj/activate, you could define any action that is to occur when the icon is activated by double clicking the first mouse button on it.

Similarly, in the object script Compress.obj/drop, you could define any action that is to occur when an icon is dragged and dropped onto it with mouse button 1.

Scope of objects

When objects are created in this manner, they are visible and available for use when you open the directory containing the object directory, referred to as the parent directory, is opened. They are also made visible if you have dragged them onto the Desktop.

If you want a particular object to appear on all users' Desktops, it is best to use the common directory called Applications. All objects that are to be universal should be defined in this directory. In addition, you should edit the Desktop rule file, described later in this manual page, so that the common directories appear by default on all user Desktops.

Rule files

Rule files are Desktop-specific configuration files. The rule files can exist in various locations on the system. Their location determines the impact the rules have on your users. For example, rules can have system-wide, directory-wide, desktop-wide or single user-wide effects, depending on which rule file they are in.

While any rule can be defined in any rule file, certain rules are better suited to particular rule files. For example, directory behavior should be specified in a local rule file; general menus should be defined in the system rule file; and a desktop-specific menu should be specified in a desktop rule file. Stand-alone applications, however, should be defined in an object.

Rule file types

The main types of rule files are:

Local rule files

define the specific behavior for the contents of the directory in which the file is located or the directory itself. The contents of a local rule file are only read when the directory containing it is opened.

For example, an archiving directory can be created which compresses any file dragged into its directory window. This information is specified in a local rule file.

The default filename is:

<directory name>/.xdtdirinfo

or as specified in the Desktop resource file. For more information on the Desktop resource file, see the Desktop resources section near the end of this manual page.

Desktop rule files

define the appearance and behavior of desktops. Generally, a desktop rule file specifies which file and directory icons are on the desktop, and their positions.

The contents of a desktop rule file are only examined when the desktop is opened. Changes made graphically to the desktop's appearance are implemented immediately; changes made to a desktop by editing the desktop rule file do not take effect until the next time the desktop is opened.

The main Desktop is specified by default in the file Main.dt in each user's home directory.

You can have additional desktops open at any time. Desktop rule files allow users to have different rules for different desktops; for example, a user might have both a programming environment and a text editing environment. A new desktop is created by defining a new desktop rule file. Desktop rule files should have the desired desktop name, followed by the extension ``.dt''. For example, the file Find.dt corresponds to the ``Find'' desktop.

The default filename is:

$HOME/Main.dt.

where $HOME represents your home directory. Desktop rule files are discussed in the Rule file section that occurs later in this manual page.

User rule files

apply only to a specific user on the system. User rule files allow users to give their desktops different appearances and behaviors.

For example, advanced users can define short cuts for all their frequently used operations, whereas less experienced users may prefer to work on a simpler system in which they are less likely to make a mistake.

The default filename is:

$HOME/.xdtuserinfo

or as specified in the Desktop resource file. For more information on the Desktop resource file, see the Desktop resources section near the end of this manual page.

System rule files

are generic or default rules that apply across the system to all users.

The contents of the user and system rule files are only examined when the Desktop starts up or after the Deskshell command reset. For more information on Deskshell commands, see the deskshell(XC) and the deskcommands(XC) manual pages.

The default filename is:

/usr/lib/X11/IXI/XDesktop/rules/system/xdtsysinfo

Dynamic rules

In addition to the rule files already discussed, dynamic rules can be used to specify rules. Unlike rule files, dynamic rules need not be specified in a particular file with a specific naming convention. Instead, dynamic rules have the following unique properties:

Dynamic rules are valid for only part of the session; they are in effect from the time they are loaded until they are unloaded.
Dynamic rules can be specified to load or take effect once particular Desktop actions occur.
Dynamic rules are loaded through the Deskshell command dynamic_rule; they need not be stored in separate files, but can be defined in-line with other deskshell commands.
Dynamic rules cannot be changed after they are loaded, but they can be unloaded by using the Deskshell command remove_dynamic_rule. For more information on Deskshell commands, see the deskshell(XC) and the deskcommands(XC) manual pages.
When they are loaded, you can specify when the dynamic rule is read in relation to other dynamic rules.

Precedence of rule files

Rule files can be located in various locations on the system, and the location determines the scope of the rule file. For example, a rule file located in a user's home directory affects only operations done by that user, and a local rule file affects only the files in the directory that contains it. The system rule file applies to all operations for all users on all files, unless it is superseded by some other rule file.

When it needs a certain rule, the Desktop searches the various rule files in the order shown later in this section; once it finds a certain type of rule, it does not look for other instances of that rule. For example, if a local rule file specifies an icon for a particular file, the Desktop does not look to see whether a different icon is specified in a desktop, user, or system rule file. Hence, the local rule file is said to ``take precedence'' over all other rule files.

The main types of rule files are searched in the following order:

Local rule files: provide rules that apply only to the files in the directory. These can be found in any directory.
Desktop rule files: provide rules that apply only to the files on the desktop. These can be found in any desktop.
Dynamic rules: are only valid if and when they are loaded. They cease to be valid if and when they are unloaded.
User rule file: defines rules that only affect the user
System rule file: contains default rules and specific global rules that apply to all desktops running on a given machine, unless different rules are explicitly defined for the directory, the desktop, or the user in a rule file or dynamic rule. There is only one such file, and it should only be changed by the system administrator.
System and user rule files are preloaded; therefore, any changes made to these files take effect the next time the Desktop is run.

See the ``Modules'' section, later, for other options on creating rules.

Internal rule precedence

This section provides a list of guidelines for which rules have precedence over others within a rule file.

In general, more specific statements take precedence over general statements. The internal precedence can be determined using the following guidelines:

Absolute pathnames have a higher precedence than relative patterns. For example, /usr/joel/.c is higher than .c.
A match is defined to be one of the following two conditions:
- pattern and a class match; for example, ``.c /F''
- specification of a required item such as a title, picture, or trigger action
If two matches are found within the same file, the first one found takes precedence.
If two matches are found in two different files, the match in the file with the higher precedence is used.

NOTE: Dynamic rules have a separate precedence hierarchy that is different than the one described here. For more information on the precedence of dynamic rules, see the Graphical Environment Guide.

Selecting a rule file

To determine the most suitable rule file in which to insert a rule, analyze the desired impact upon users. First, evaluate how widespread a particular rule's effect should be. Second, consider the type of rule being inserted. Certain rule types are well-suited for particular rule file types (desktop_layout rules are suited for the desktop rule file, for example).

The following is a list of general guidelines to follow when choosing a rule file:

In general, any behavior that should be restricted to a particular environment should be defined in a local rule file.
Any rule that could be potentially disruptive should be placed in a desktop or a local rule file first, and then tested. This way, the rest of the Desktop remains unaffected, even if undesirable behavior occurs.
Any actions that are relevant to the general appearance and behavior of a desktop should be placed in the desktop rule file. For example, menus specific to a desktop should be inserted there.
locked_on_desktop and desktop_layout rules, for example, are inherently desktop-wide issues and therefore are well suited for the desktop rule file.
Any rules that a user requires all the time, but are not relevant to all users, should be placed in the user rule file. Rules placed in here will be available to the user at any time, in any directory or any desktop (unless they are over-written by a higher precedence rule in a local or desktop rule file).
Rules placed in the system rule file affect all users on the system. In general, do not edit the system rule file unless the actions defined are essential to all users and cannot be handled through any other Desktop means.
Because user rule files exist to allow users to customize their desktops, the system rule file should limit itself to rules governing system operation, user interaction, and default values.
Dynamic rules should be used for rules that are needed for only part of a session or that are required while running a particular program.
Dynamic rules are used in special circumstances and should not be chosen for rules that are frequently used within a session.

Modules

Modules are a feature that make the rules more modular and, therefore, easier to upgrade. A module is a set of rules that are loaded at system startup and act as if they are in the system rule file. Because they are not actually located in the system rule file, however, they are easy to support and users do not have to try and understand the system rule file's complexity to make modifications to the Desktop behavior. Modules are placed in /usr/lib/X11/IXI/XDesktop//rules/modules.

A module can be specified to work on a per-user or per-group basis. For example, the group ``Support'' can be specified to use modules a, b, and c, whereas the group ``Staff'' or user ``john'' only use module a. This is accomplished through a series of resources, a few examples of which are shown below:

XDesktop3.Rules.defaultModules:: used by all users
XDesktop3.Rules.support.groupModules:: used by all users in group ``Support''
XDesktop3.Rules.john.userModules:: used by user ``john'' only

As part of the system file layout, modules can be written and placed in a special directory ($HOME/.xdt_dir/modules), where they only take effect for that user.

Modules written with the .auto extension are special modules that are always loaded at startup. The purpose of these modules is for easy installation of new rules and/or applications. Installation of a new application with special rules only needs to locate the modules directory and insert a new .auto module containing these rules.

Modules written with the Loop_ prefix work in exactly the same way as normal modules but are performed within a background loop. The loop is run upon startup and then every n seconds, where n is defined by the resource XDesktop3.rules.LoopDelay. A loop module is only run if it is listed in the XDesktop3.Rules.defaultLoopModules resource. This again has all the benefits of a module and is used to avoid multiple loops.

For optimum performance, these rule modules should be quite short. A good example of a loop module is a mail checker or directory contents checker.

If you want a new module to run every tenth time the main loop is run, this can be carried out by means of a simple counter within the module itself. See the following .auto module example:

   idr -F filecheck_rule `
   icon_rules
   {
      * /F
      {
        trigger_action: activate
        {
           message This file is $static_arg
         }
      }
   }'

If the above file is placed in a user's $HOME/.xdt_dir/modules directory and called filecheck.auto, for example, then after a restart, if the user double-clicks on any file with mouse button 1, an fyi box appears and provides the full pathname of the file.

Rules

Rules, found within rule files and dynamic rules, can be used to configure icon pictures, icon titles, desktop layout, actions of the mouse, menus, actions associated with different directories on the Desktop, and many other variable aspects of the Desktop. Rules are also used to specify the behavior of all icons, menus, and directories.

Elements of a rule file

The rules are divided into clauses that can be in six main categories, defined as: icon_rules, locked_on_desktop, desktop_layout, initial_actions, final_actions, and menu. There are also sub-rules or sub-clauses to each of these types:

icon_rules: These rules define the appearance and behavior of icons. They describe what the icon for each file looks like (which picture file contains the artwork and what the icon title is) and what occurs when an icon is invoked by a mouse action.
locked_on_desktop: These rules list the icons that are locked onto a desktop and cannot be removed with the Put Back menu item.
desktop_layout: These rules list which icons are initially on a desktop and their positions.
initial_actions: These rules specify the actions taken when the rule file is first opened. System and user rule files are opened when the Desktop process is first started. Directory and desktop rule files are opened when their associated windows are opened.
final_actions: These rules specify the actions taken when the rule file is closed. Rules files are closed in a parallel fashion to the way they are opened (see the preceding initial_actions entry).
menu: These rules define the title and items of a menu and what happens when any item on the menu is selected.

For a detailed description of these clauses, including appropriate syntax, see ``Rule file clause and keyword descriptions''.

Effects of different rule types in different rule files

The following table illustrates the effects of various rule types in the different types of rule files.

Rule type Local rule Desktop User rule System Dynamic

files rule files files rule files rules

icon_rules Affect icons in directory containing rule file Affect icons on desktop Affect all of the user's icons Affect all icons Affect all icons while loaded

locked_on_desktop Ignored Applies to desktop Applies to main desktop

desktop_layout Ignored Applies to desktop Applies to desktops not already holding a desktop_layout clause

initial_actions When directory is opened When desktop is opened When the Desktop starts When the rule file is installed

final_actions When directory is closed When desktop is closed When the Desktop exits When the rule file is removed

menu Available in the directory the rule file is in Available in desktop it is in Available in all directories and desktops

Rule type	Local rule	Desktop	User rule	System	Dynamic
	files	rule files	files	rule files	rules
icon_rules	Affect icons in directory containing rule file	Affect icons on desktop	Affect all of the user's icons	Affect all icons	Affect all icons while loaded
locked_on_desktop	Ignored	Applies to desktop	Applies to main desktop
desktop_layout	Ignored	Applies to desktop	Applies to desktops not already holding a desktop_layout clause
initial_actions	When directory is opened	When desktop is opened	When the Desktop starts	When the rule file is installed
final_actions	When directory is closed	When desktop is closed	When the Desktop exits	When the rule file is removed
menu	Available in the directory the rule file is in	Available in desktop it is in	Available in all directories and desktops

Rule syntax

You must follow syntactical guidelines and use conventional layout when writing rules. The following guidelines apply:

Rule files and object scripts are text files that can be created and edited using any program editor, such as vi or scoedit.
Rules are blocked structures such as the C or Pascal programming language.
Rule and clause types can appear in any order and in any number.
One rule file need not include all the rules. For example, a user can include only locked_on_desktop rules in a user rule file and use a system rule file for all other rules.

Structure of rule files

A rule file or an object script is made up of a sequence of clauses. Each clause or rule can have one of the two following forms:

keyword = value ;

or

keyword = { body }

where the body is normally a sequence of further clauses or a Deskshell script that specifies a system action to be taken. For more information on Deskshell, see the deskshell(XC) and the deskcommands(XC) manual pages.

Rule files are blocked structures; in general, their layout is not important. For example, the following two rules are equivalent:

   icon_rules {* /D{picture=dir.px;}* /F{picture=file.px;}}

and:

   icon_rules
   {
      * /D
      {
        picture = dir.px ;
      }
      * /F
      {
        picture = file.px ;
      }
   }

However, the second format is recommended. It is easier to identify the structure of the rule and to match brackets, making it easier to debug.

Using keywords

Each rule or clause within a rule is introduced by a keyword. Keywords can be entered in long, descriptive forms or in short, two-letter forms. For example, icon rules are introduced either by the keyword icon_rules or the abbreviation ic. The following table lists the valid keywords with their abbreviations and definitions. For a detailed description of these keywords, see ``Rule file clause and keyword descriptions''.

Rule type Keyword Abbr. Definition

Section keywords icon_rules ic describe the appearance and behavior of files that are represented by icons

locked_on_desktop lf specifies icons that are to be locked on the Desktop

desktop_layout dt describes the icons on the Desktop and their positions

initial_actions ia specify actions when the rule file is first opened

final_actions fa specify actions when the rule file is closed

menu me defines the items on menus and the actions to be performed when a particular item is selected

Common
subclauses trigger_action ta specifies the actions to be performed when a specified trigger occurs with the mouse pointing to the icon

Subclause in directory rules and desktop rules drop_in_action da specifies the actions to be performed when the specified dynamic trigger occurs on a directory window or icon

Subclauses in menu rules menu_item mi specifies an item on a menu and the action to be performed when the item is selected

pull_off_menu pm specifies a subsidiary menu that cascades off the named menu, leaving both the current menu and the pull_off_menu visible on the screen

dividing_line dv=n puts line in menus

thick_dividing_line dv=t

enable_if specifies an action to determine if the menu command is selectable, or dimmed out

select_action specifies the actions to be performed when a command is selected

Subclauses in icon rules picture pi assigns a picture file to the specified file or group of files

title ti assigns a title to be displayed with the icon

attribute at allows attributes to be assigned to a file or group of files

Rule type	Keyword	Abbr.	Definition
Section keywords	icon_rules	ic	describe the appearance and behavior of files that are represented by icons
	locked_on_desktop	lf	specifies icons that are to be locked on the Desktop
	desktop_layout	dt	describes the icons on the Desktop and their positions
	initial_actions	ia	specify actions when the rule file is first opened
	final_actions	fa	specify actions when the rule file is closed
	menu	me	defines the items on menus and the actions to be performed when a particular item is selected
Common subclauses	trigger_action	ta	specifies the actions to be performed when a specified trigger occurs with the mouse pointing to the icon
Subclause in directory rules and desktop rules	drop_in_action	da	specifies the actions to be performed when the specified dynamic trigger occurs on a directory window or icon
Subclauses in menu rules	menu_item	mi	specifies an item on a menu and the action to be performed when the item is selected
	pull_off_menu	pm	specifies a subsidiary menu that cascades off the named menu, leaving both the current menu and the pull_off_menu visible on the screen
	dividing_line	dv=n	puts line in menus
	thick_dividing_line	dv=t
	enable_if		specifies an action to determine if the menu command is selectable, or dimmed out
	select_action		specifies the actions to be performed when a command is selected
Subclauses in icon rules	picture	pi	assigns a picture file to the specified file or group of files
	title	ti	assigns a title to be displayed with the icon
	attribute	at	allows attributes to be assigned to a file or group of files

Using special characters

The following table shows special characters that are recognized when included within rules:

Character Meaning

= is an assignment operator

! is an assignment separator

{ (open brace)
} (close brace} groups together statements within a rule block

% (percent) introduces special phrases and instructions; is used as an escape sequence for shell metacharacters and special characters listed in this table

; (semicolon) terminates other items; is optional when followed by a close brace

%// marks the beginning of a one-line comment

(white space) is ignored except in special cases, such as in the literal text supplied as an icon title

If the name does not begin with a slash, it is interpreted as relative to a directory, depending on the type of rule file being processed:

Character	Meaning
=	is an assignment operator
!	is an assignment separator
{ (open brace) } (close brace}	groups together statements within a rule block
% (percent)	introduces special phrases and instructions; is used as an escape sequence for shell metacharacters and special characters listed in this table
; (semicolon)	terminates other items; is optional when followed by a close brace
%//	marks the beginning of a one-line comment
(white space)	is ignored except in special cases, such as in the literal text supplied as an icon title

Rule file Directory for relative includes

local rule files same directory

dynamic rules $HOME

desktop rule files $HOME

user rule files $HOME

system rule files same directory

object directory same directory

Because spaces are used to separate field in rule files, you should put a string in single quotes if it includes spaces. For example, type

echo 'Press return'

Rule file	Directory for relative includes
local rule files	same directory
dynamic rules	$HOME
desktop rule files	$HOME
user rule files	$HOME
system rule files	same directory
object directory	same directory

to display Press return

NOTE: If the single quote is to be used in a string, include two successive single quotes (").

Strings should also be enclosed in quotes if you want to include any of the special characters (such as {}=;`).

Using variables

In rule files or in object scripts, variables can be used to monitor numbers and text strings. Using variables, the user can keep track of the number of files that need to be processed in a particular directory. Variables also can be used to store the actual filenames yet to be processed in a directory. Alternatively, variables can be used to search for a particular string in a filename in a given directory or the Desktop.

Variables give additional flexibility when you are writing rules that manipulate components of the Desktop.

A variable name can be any sequence of letters, digits, and underscores provided that the first character is not a digit. Variables beginning with two underscores are discouraged because this naming convention is used in the standard rules (however, one leading underscore is permissible).

Unlike most programming languages and shell scripts, variables need not be specially defined, and they are assigned values with the equals sign (=). For example,

   count=10

assigns the numeric value 10 to the variable count.

For further flexibility, variables can be assigned a list of values. The list is specified by putting all of the list elements in brackets. For example,

   editors=(vi scoedit ed)

assigns the variable editors a list of the names of three editors on the system.

The values of variables can be accessed in a rule file or object script by using the ``$'' operator. Specific elements in a variable list can be extracted by putting one or more element numbers in parentheses after the variable name. While

   $editors

has the value: ``vi scoedit ed'';

   $editors(2)

has the value: ``scoedit''

You can find the number of elements in a variable list with the ``$#'' operator. For example,

   $#editors

yields the value 3.

The element can come from another variable or construct. For example,

   $editors($#editors)

has the value: ``ed''.

Environment variable values can also be included in a rule file by using the operator ``$''. Catenation is also allowed. For example,

   $HOME/fred
   $HOME^/abc

are both acceptable.

Using substitutions

Substitutions are used in action clauses. These clauses link mouse manipulations of the object or triggers with system or Desktop actions. They allow the action to specify the filename of an icon that is affected when it is dropped or triggered.

The following special sequences can be substituted in picture and title clauses in icon_rules clauses:

String Meaning

%B0 basename of the file

%C0 class of the file, given as six characters in standard order

%D0 absolute pathname of the directory holding the file

%E0 basename without the suffix (dot and characters following the dot)

%P0 absolute pathname of the file

%R0 relative pathname of the file. When a title clause is being expanded within a directory window, this is the same as B.

String	Meaning
%B0	basename of the file

%C0	class of the file, given as six characters in standard order
%D0	absolute pathname of the directory holding the file
%E0	basename without the suffix (dot and characters following the dot)
%P0	absolute pathname of the file

%R0	relative pathname of the file. When a title clause is being expanded within a directory window, this is the same as B.

Specifying file and directory pathnames

The Desktop uses standard UNIX operating system conventions for referencing the pathname of a file. The values in parentheses are substitutions that can be used to reference the various types of pathnames. Substitutions are discussed later in this manual page.

A file can be referred to in one of the following ways:

absolute pathname (%P0): pathname of the file starting from the root directory (/)
basename (%B0): name of the file within its directory. This is the part of the absolute pathname following the last slash.
dirname (%D0): absolute path of the directory holding the file. It is the part of the absolute pathname that precedes the last slash.
relative pathname (%R0): name of the file relative to the user's present working directory. This is true only if the file is in the user's home directory or one of its subdirectories. Otherwise, it is the same as the absolute pathname.

The following example shows the pathname reference for the file /people/fred/work/letter:

Absolute pathname: /people/fred/work/letter

Basename: letter

Dirname: /people/fred/work

Relative pathname: determined by present working directory:

Working directory: Relative pathname:

/ people/fred/work/letter

/people fred/work/letter

/people/fred work/letter

/people/fred/work letter

any other /people/fred/work/letter

NOTE: There is one exception. The dirname of ``/'' is slash dot (/.), and its basename is slash (/).

Deskshell command language

Rules are defined using commands and scripts. You can specify regular UNIX operating system binaries and shell scripts in your rules. However, it is recommended that you learn how to use the Deskshell commands and scripts. Deskshell is a command language, complete with a flexible range of control structures and a wide range of commands.

Because Deskshell is designed specifically for use with the Desktop and because Deskshell commands execute significantly faster than regular UNIX shell commands, Deskshell commands are recommended for coding your script. For more information on writing scripts using Deskshell, including how to use Deskshell syntax and commands, see the deskshell(XC) and the deskcommands(XC) manual pages.

Desktop resources

You can customize some characteristics of the Desktop by editing your personal Desktop resource file; this file contains user preferences for the Desktop client. If the file does not already exist, create it with the full pathname:

$HOME/XDesktop3

where $HOME represents your home directory.

Alternatively, you can create your own X resource file that contains user preferences for all clients instead of just the Desktop. If the file does not already exist, create it with the full pathname:

$HOME/.Xdefaults-hostname

where hostname is the name of the machine.

Either of the above files may be used to include Desktop resources, although the .Xdefaults-hostname resource file takes precedence over the XDesktop3 resource file.

Once you create one or both of these files, copy relevant resources from the Desktop resource file into one of them and change them to suit your specific needs. The Desktop resource file is /usr/lib/X11/app-defaults/XDesktop3.

The most useful resources are listed here.

xdt3.isRoot: If ``True'', specifies that the main Desktop occupies the whole root window. The default is ``True''. The isRoot window obeys any geometry specified for the first (main) window. This means the isRoot window can be smaller than the screen.
It is strongly recommended that users change this behavior by using the Desktop Preferences Editor utility on the Desktop rather than in a resource file.
xdt3.isRoot.focusToggle: Specifies the key combination that makes the Desktop grab the keyboard focus. The default is <Shift><Alt><F2>.
If isRoot is set, it is necessary to assign a key to toggle keyboard focus in order to be able to use the menu accelerators or answer prompts on the isRoot desktop window.
xdt3pictureDirectory: Specifies the search path for the icon picture files (will expand to $HOME). The default is:

$XDTBITMAPS/xdt_c_large,
$XDTBITMAPS/xdt_large,
$HOME/.xdt_dir/bitmaps/xdt_large, and
/usr/include/X11/bitmaps.
xdt3.systemRuleFile: Specifies where to find the system rule file. The default is /usr/lib/X11/IXI/XDesktop/rules/system/xdtsysinfo.
xdt3.userRuleFile: Specifies the name of the user rule file. The default is .xdtuserinfo
xdt3.directoryRuleFile: Specifies the name of the directory rule files. The default is .xdtdirinfo
xdt3.windowInfoCacheSize: Specifies the number of trays (Desktop and/or directories) that are cached. The default is ``0'' (increasing this number may cause a minor overall performance loss while decreasing the time to reopen directories).
xdt3.triggers.thresholdDownTime: Specifies the distinction between a click and a hold. If the button is held down for longer than the value of this resource, the action is a hold. The default is ``700'' milliseconds.
xdt3.triggers.maxUpTime: Specifies the distinction between a single and a double click. If the button is released for longer than the value in this resource, the action is a single click. The default is ``500'' milliseconds.
xdt3.desktop.menubar: Specifies the name of the menu rule that defines the contents of the desktop menu bar (to be used in rule files). The default is ``DesktopMenuBar''.
xdt3.directory.menubar: Specifies the name of the menu rule that defines the contents of the directory menu bar (to be used in rule files). The default is ``DirMenuBar''.
xdt3.directory.maxFiles: Specifies the maximum number of files that can be in a directory. The default is ``10000''.

NOTE: There are numerous resources regarding colors that appear on the Desktop. Colors should always be defined in terms of SCO OpenServer palette colors, otherwise there is a risk of overflowing the colormap. Furthermore, it is better to use the scocolor client to change colors as opposed to re-defining resources. For more information on the scocolor client, see the scocolor(XC) manual page.

Rule file clause and keyword descriptions

The following sections provide detailed descriptions of the rule file clauses and keywords:

attribute [at]

A component of icon_rules clauses to assign an arbitrary string to specified pathnames.

Syntax

attribute: name=string ;

where:

name: a single word containing only letters, digits, hyphens, and underlines
string: the string to be assigned to 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)
         }
      }
   }

See also:

get_attribute, which returns the values of specified attributes

desktop_layout [dt]

A rule file clause that describes which files are on a desktop, together with their positions. It is normally generated automatically by the Desktop.

Syntax

desktop_layout { [ filename [@ position ] ; ] . . . }

where:

filename

name of the file

position

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

F: first free position in the grid (default)
Gx,y: position in the standard tidying grid. ``0,0'' is top left.
Px,y: position in pixels
V: the Desktop will pick a position

Description

When the Desktop writes a desktop_layout clause back to a desktop file, it appends the clause to the front of the original contents of the file, prefixed by the header shown below.

Any other desktop_layout clauses in the file will thereafter be ignored, and can be removed.

Each desktop_layout clause subsequently written back to the file will replace the one following the ``%/dt/'' header. If the clause is edited by hand in any way, or another clause is placed in front of it, the ``%/dt/'' header should be removed.

%/dt/

%// WARNING

%// This file has had a new DT clause inserted. If there was a previous %// DT clause in the file, it will not have been removed, but it will be %// ignored by X.desktop from now on. %// We suggest you search this file for a second DT clause (not the one %// immediately following this comment), and delete both it and this %// comment.

%// A DT clause has the form dt { . . . } or desktop_layout { . . . }.

dt { . . . contents of new desktop_layout clause . . . }

The comments can be removed without ill effect.

Example

Your main Desktop file, $HOME/Main.dt, might contain the following desktop_layout clause:

   desktop_layout
   {
   %$HOME$ @G0,0;
   %$HOME$/Personal.dt @G1,0;
   /usr/lib/X11/IXI/XDesktop/tools/Accessories.ts/Edit.obj @G2,0;
   /usr/lib/X11/IXI/XDesktop/tools/System.ts/Shell.obj @G3,0;
   /usr/lib/X11/IXI/XDesktop/tools/Devices.ts/Printer.obj @G4,0;
   /usr/lib/X11/IXI/XDesktop/tools/Accessories.ts/Help.obj @G5,0;
   /usr/lib/X11/IXI/XDesktop/tools/Accessories.ts @G0,1;
   /usr/lib/X11/IXI/XDesktop/tools/Controls.ts @G0,2;
   /usr/lib/X11/IXI/XDesktop/tools/Accessories.ts/Mail.obj @P201,372;
   %$HOME$/trash.dt @G0,3;
   }

dividing_line [dv=n]

Defines a dividing line on a menu.

Syntax

dividing_line

Description

A component of menu clauses which gives a thin dividing line between menu commands.

Example

The following menu includes a dividing line between the first and second menu commands:

   menu: Applications
   {
      menu_item: Clock
      {
         shell_window xclock
      }
      dividing_line ;
   
      menu_item: Shell
      {
         shell_window
      }
   }

See also:

thick_dividing_line, which gives a thick dividing line

drop_in_action [da]

A component of the icon_rules clause which specifies the actions to be performed when a specified trigger occurs with the mouse pointing to the background of a window.

Syntax

drop_in_action: trigger { script }

where:

trigger

the name of a trigger, which can be one of:

drop or alt_drop (when referring to windows, not icons)
report or alt_report
deselect
popup_menu

script

a Deskshell script specifying the actions to be performed

Description

The script can be blank, in which case the trigger will have no effect. For example, the following clause specifies that trigger report on a directory window background should do nothing:

   icon_rules
   {
      * /D
      {
         drop_in_action: report { }
      }
   }

Example

In the following example, When the user double-clicks with the alternate mouse button on a directory window background, the window will be closed:

   icon_rules
   {
      * / D
      {
         drop_in_action: alt_report
         {
           
            close_directory $static_arg
         }
      }
   }

See also:

trigger_action, which specifies actions to be performed when an icon is triggered in a particular way

enable_if

A property of menu_item clauses which specifies an action to determine if the menu command is selectable, or grayed-out. If not specified, the command is always selectable.

Syntax

enable_if { script }

Description

If a menu command has an enable_if clause, it will only be selectable if the specified action returns a true status.

When the user selects a menu, all the enable_if clauses in the menu definition are executed, in the order of the menu entries, by a priority thread which is a child of the window thread for the window displaying the menu.

Each item is enabled only if status is true after the corresponding script is executed.

If a menu command has no enable_if clause, this is equivalent to:

enable_if { true }

An empty script, or one that does not affect status, sets the state of the command to the same as the previous one.

Only the following commands are allowed in priority scripts:

!= -class -eq

-ge -gt -le

-lt -ne -same

= == absreadlink

basename break canonical

cd continue declare

dirname eval exit

extension false fileclass

followlink get_attribute get_resource

join list commands merge

pwd query commands readlink

relativepath return sequence

split tolower toupper

true unextended variables

Functions are permitted in priority threads, but not external programs.

Example

The following example enables a menu item only if a single icon has been selected on the desktop:

   menu: DesktopMyMenu
   {
     menu_item
     {
       title=MyItem;
       enable_if
       {
         -eq 1 `(list count `(query selections `(query thread_info -i $thread_name
       }
       select_action
       {
         # ...script...
       }
     }
   }

final_actions [fa]

Specifies a set of actions to be executed when the rule file is closed.

Syntax

final_actions { script }

where:

script: a Deskshell script specifying the actions to be performed

Description

The system thread initially executes the initial_actions clauses in the system and user rule files, and then changes to suspended state.

When a dynamic rule is loaded or unloaded using dynamic_rule or remove_dynamic_rule with the -x flag, the system thread changes to the ready state and executes the appropriate initial_actions or final_actions clause. It then reverts to suspended state.

When the Desktop receives a die command to shut it down, the system thread executes the final_actions clauses in the user and system rule files, and then terminates.

Each desktop or directory window thread initially executes the initial_actions clause in the directory or desktop rule file, and then changes to suspended state. When the window is closed the thread executes the final_actions clause and then terminates.

Example

The following example in a system or user rule file displays a dialog box when the user exits from the Desktop:

   final_actions
   {
      for_info 'Have a nice day!'
   }

See also:

initial_actions, which specifies actions to be executed when the rule file is opened

icon_rules [ic]

A rule clause that describes the behavior and appearance of icons.

Syntax

icon_rules
{
pattern [/class] { clauses }
}

where:

pattern

pattern matching filenames to which clauses should apply; see below

class

classes of file to which clauses should apply; see below

clauses

one or more of the following:

title clause: to specify the title for the matched icons
picture clause: to specify the picture for the matched icons
trigger_action clauses: to specify the action for specified triggers on the matched icons
attribute clauses: to specify attributes for the matched icons

Description

The clauses apply to files matching the specified pattern and class. The pattern can be absolute or relative.

Patterns

Patterns look like filenames or pathnames, but can contain certain special characters or wildcards. There must be at least one space or newline before the /class.

The basename of a pattern can include the following wildcard characters:

?: any character. For example, ``a?c'' includes the files abc and aac, but not the file abbc.
*: any sequence of characters, including none. For example, ``a*c'' includes the files ac, abc, and acbc.
[chars]: any of the specified set of characters. For example, ``a[bc]d'' includes the files abd and acd, but no others.
[!chars]: none of the specified characters. For example, ``a[!bc]d'' will not include the files abd and acd.

These patterns can be combined. For example, ``[!A]*'' means any file beginning with a character other than A.

Relative patterns

If the pattern does not begin with a ``/'', it is a ``relative pattern'', which can match files anywhere in the system. The pattern cannot include ``/''.

Rules following relative patterns in a local rule file apply to files in the directory that match the pattern. Rules following relative patterns in all other rule files apply to all files whose basenames match the pattern.

Absolute patterns

If the pattern begins with a ``/'', it is an ``absolute pattern'', which will match only files in a specific directory. Absolute patterns cannot occur in local rule files. Wildcards can only be included after the last ``/'' in an absolute pattern.

Rules following absolute patterns apply to files in the directory given by the pattern up to the last ``/'', and whose basename matches the part after the last ``/''. These rules take precedence over those following relative patterns in any rule file.

Classes

Classes are used to represent the properties of files in a concise form. For a complete explanation of classes, see ``fileclass''.

Example

The following example defines a rule that will cause any icons dropped on a directory icon to be moved into that directory:

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

initial_actions [ia]

Specifies a set of actions to be executed when the rule file is opened.

Syntax

initial_actions { script }

where:

script: a Deskshell script specifying the actions to be performed

Description

The system thread initially executes the initial_actions clauses in the system and user rule files, and then changes to suspended state.

When a dynamic rule is loaded or unloaded using dynamic_rule or remove_dynamic_rule with the -x flag, the system thread changes to ready state and executes the appropriate initial_actions or final_actions clause. It then reverts to suspended state.

When the Desktop receives a die command to shut it down, the system thread executes the final_actions clauses in the user and system rule files, and then terminates.

Example

The following clause in an .xdtdirinfo file in the user's home directory will display a message whenever the directory is opened:

   initial_actions
   {
      for_info 'Welcome to your Home directory'
   }

See also:

final_actions, which specifies actions to be performed when the rule file is closed

locked_on_desktop

Specifies icons to be displayed permanently on a desktop.

Syntax

locked_on_desktop { filename ; . . . }

where:

filename: files to be locked onto the desktop

Description

A locked_on_desktop clause applies as follows:

System and user rule files: to the main Desktop
Desktop rule file: to that desktop
Local rule file: ignored

Example

The following example locks the root, /bin and /usr/bin directory icons onto the desktop.

   locked_on_desktop
   {
      /        ;
      /bin     ;
      /usr/bin
   }

menu_item [mi]

A component of menu clauses which defines a menu command, and the action to be performed when the command is selected.

Syntax -- short form

menu_item: cmdname { script }

where:

itemname: the name of the menu function
script: the commands to be executed when the user chooses the function, or empty, which gives itemname as a centered title for the menu, or a pull_off_menu menu clause; see pull_off_menu

Syntax -- long form

menu_item tag
{
title=cmdname;
select_action { script }
enable_if { enablescript }
pull_off_menu=menuname;
}

where:

tag: an item tag used by menu_actions_of for resource fetching
cmdname: the name of the menu command or function
script: the commands to be executed when the user chooses the function
enablescript: script executed to determine whether the menu function is enabled or disabled; see ``enable_if''
menuname: the name of a pull_off_menu clause; see pull_off_menu

Description

The select_action and pull_off_menu clauses cannot both be present.

The cmdname can include the string:

_X_Y_Z

which defines:

X as a mnemonic letter for the command, which must be one of the letters in cmdname
Y as an accelerator key equivalent for the menu command or function
Z as text to be displayed right-justified in the menu to show the accelerator key.

For example:

Open__Ctrl<Key>O_: defines ``[Ctrl]O'' as an accelerator for the menu command Open. There is no mnemonic, and the accelerator key is not shown on the menu.
New_N__: defines ``N'' as a mnemonic for the menu command New. There is no accelerator key.

Example

The following menu_item commands define New File and New Directory menu commands:

   menu_item: New File_F_Ctrl<Key>F_Ctrl+F
   {
      make_new_file $static_arg
   }
   menu_item: New Directory_D_Ctrl<Key>D_Ctrl+D
   {
      make_new_file -d $>static_arg
   }

See also:

menu, which defines a menu
pull_off_menu, which defines a cascade menu

picture [pi]

A component of icon_rules clauses which assigns a picture file to the files specified in the file specification.

Syntax

picture=[filename] ;

where:

filename: picture filename, usually with a .px extension

Description

The list of directories to be searched is specified by the *pictureDirectory resource. If no filename is specified, the icon will not be displayed.

Example

The following rule specifies that all directories are to use the picture in the picture file dir_rw_o.px.

   icon_rules
   {
      * / D { picture=dir_rw_o.px }
   }

The following rule hides all files beginning with a ``.'' (dot):

   icon_rules
   {
      .* / F { picture= }
   }

See also:

``%'', for a list of special sequences that can be substituted in picture clauses

pull_off_menu [pm]

A component of menu_item clauses which defines a menu command to display a cascade menu.

Syntax

pull_off_menu=menuname ;

where:

menuname: the name of a menu command defining the cascade menu

Example

The following example defines a Sort cascade menu:

   menu_item: Sort      _Sort__
   {
      pull_off_menu=DirSortMenu
   }
   
   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:

menu, which defines a menu
menu_item, which defines each command in a menu

select_action

A component of menu_item clauses which specifies the actions to be performed when the command is selected from the menu.

Syntax

select_action { script }

Example

The following menu_item clause defines a Greeting menu command which displays the Desktop greeting window:

   menu_item
   {
      title=Greeting;
      select_action
      {
         show_greeting
      }
   }

See also:

enable_if, which specifies whether a menu command is enabled or disabled

thick_dividing_line [dv=t]

Defines a thick dividing line on a menu.

Syntax

thick_dividing_line

Description

A component of menu clauses which gives a thick dividing line between menu commands.

Example

The following menu includes a thick dividing line between the first and second menu commands:

   menu: applications
   {
      menu_item: Applications {}
   
      menu_item: xclock
      {
         xclock
      }
      thick_dividing_line ;
     
      menu_item: shell
      {
         shell_window"
      }
   }

See also:

dividing_line, which gives a thin dividing line

title [ti]

A component of icon_rules or menu_item clauses which assigns a title to an icon or menu command respectively.

Syntax

title=name;

Example

The following clause sets the title of the xcalc program:

   icon_rules
   {
      xcalc /F
      {
         title=Calculator;
      }
   }

See also:

``%'', for a list of special sequences that can be substituted in title clauses

trigger_action [ta]

A component of the icon_rules clause which specifies the actions to be performed when a specified trigger occurs with the mouse pointing to the icon.

Syntax

trigger_action: trigger { script }

where:

trigger: the name of a trigger or * (any trigger), s* (any static trigger), d* (any drag trigger), or h* (any hold trigger) See ``Trigger descriptions'' for a list of all available triggers.
script: a Deskshell script specifying the actions to be performed

Description

The script can be blank, in which case the trigger will have no effect. For example, the following clause specifies that trigger alt_activate on a directory should do nothing:

   icon_rules
   {
      * /D
      {
         trigger_action: alt_activate { }
      }
   }

Example

In the following example, when any directory is activated, a directory window is opened to show the contents of that directory in time order:

   icon_rules
   {
      * / D
      {
         trigger_action: activate
         {
            display_directory -t $*
         }
      }
   }

Trigger descriptions

The following sections provide detailed descriptions of the Desktop triggers:

* (trigger)

Matches any trigger.

Syntax

trigger_action: *

Description

The following trigger action will occur when an icon is triggered with any trigger, using any mouse button.

   
   trigger_action: *
   {
      ...actions...
   }

See also:

d*, which matches any drag trigger
h*, which matches any hold trigger
s*, which matches any static trigger

activate

Activates an icon.

Syntax

trigger_action: activate

Example

The following icon rule displays a for_info dialog box when the test icon is activated:

   icon_rules
   {
      test
      {
         trigger_action: activate
         {
            for_info 'Testing'
         }
      }
   }

alt_activate

Activates an icon with the alternate mouse button, usually mouse button 2.

Syntax

   trigger_action: alt_activate

See also:

activate, the trigger action for activating an icon

alt_drop

The trigger action for dragging an icon and dropping it onto another icon or a window background with the alternate mouse button.

Syntax

trigger_action: alt_drop

See also:

drop, the trigger action for dragging and dropping an icon

alt_rename

The trigger action for clicking on the title of an icon with the alternate mouse button.

Syntax

trigger_action: alt_rename

See also:

rename, the trigger action for clicking on the title of an icon

alt_report

The trigger action for double-clicking on a window background with the alternate mouse button.

Syntax

drop_in_action: alt_report

See also:

report, the trigger action for double-clicking on a window background

alt_select

Selects with the alternate mouse button.

Syntax

trigger_action: alt_select

See also:

select, the trigger action for selecting icons

copy

Copies an icon.

Syntax

trigger_action: copy

d*

Matches any dynamic trigger.

Syntax

trigger_action: d*

Example

The following example displays the name of the icons dropped onto this icon with any drag trigger:

   icon_rules
      * /F
      {
         trigger_action: d*
         {
            if == $#dynamic_args 1
            then
               for_info '$dynamic_args was dropped on this icon'
            else
               for_info '$dynamic_args were dropped on this icon'
            fi
         }
      }
   }

See also:

*, which matches any trigger
h*, which matches any hold trigger
s*, which matches any static trigger

deselect

Deselects icons.

Syntax

trigger_action: deselect

discard

Discards an icon.

Syntax

trigger_action: discard

Example

The following Trash icon script sends the discard trigger to all the icons dropped onto the Trash icon to discard each icon.

   for i
   do
      do_actions_of discard $i $static_arg
   done

The loop is executed with $i equal to each string in the list $*.

drop

The trigger action for dragging an icon and dropping it onto another icon or a window background.

Syntax

trigger_action: drop

See also:

alt_drop, the trigger action for dragging and dropping an icon with the alternate mouse button

duplicate

Duplicates an icon.

Syntax

trigger_action: duplicate

Example

The standard definition of the Duplicate command 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, represented by the icon triggered, and runs it, passing the current value of $dynamic_args as the objects for the trigger action to use as its $dynamic_args.

h*

Matches any hold trigger.

Syntax

trigger_action: h*

Description

The following trigger action will occur when any hold trigger is caused on the icon:

   trigger_action: h*
   {
      actions
   }

Buttons 1 and 2 can be used for hold triggers by rewriting the *trigger.mapping resource. However, bear in mind that:

the OSF/Motif standard specifies that only mouse button 3 be used for pop-up menus
as only a hold trigger is defined for mouse button 3, using other buttons will increase the time taken to pop up the menu

See also:

*, which matches any trigger
d*, which matches any drag trigger
s*, which matches any static trigger

move

Moves an icon.

Syntax

trigger_action: move

Example

The default move action, for icons with no alternative move action, is:

   icon_rules
   {
      *
      {
         trigger_action: move
         {
            name =`(basename $static_arg)
            for_info -h moving -t 'Icon: '^$name 'You may not move this icon.'
         }
      }
   }

popup_menu

The trigger action for holding with mouse button 3 on a window background.

Syntax

trigger_action: popup_menu

rename

The trigger action for clicking on the title of an icon.

Syntax

trigger_action: rename

Description

Do not confuse the rename trigger (defined in the trigger mappings as corresponding to a single click on an icon title) with the rename Deskshell command (which renames a file in the filing system).

report

The trigger action for double-clicking on a window background.

Syntax

drop_in_action: report

Example

The following example checks all icons and does a refresh when you double-click on the background of a directory:

   icon_rules
   {
      SomeDir /D
      {
         trigger_action: report
         {
            check -D $static_arg
            action swap open_new $static_arg
         }
      }
   }

s*

Matches any static trigger.

Syntax

trigger_action: s*

Description

The following trigger action occurs when any static trigger is applied to an icon (a double-click with mouse button 1 or 2). Mouse button 3 defaults to a menu, but can be used as a static trigger with some rewriting of the trigger table, using the *trigger.mapping resource. See h*, for the potential consequences of this action.

   
   trigger_action: s*
   {
      actions
   }

See also:

*, which matches any trigger
d*, which matches any dynamic trigger
h*, which matches any hold trigger

select

Selects icons.

Syntax

trigger_action: select

Files

$HOME/Main.dt
$HOME/.Xdefaults-hostname
$XDTBITMAPS/*
/usr/include/X11/bitmaps
/usr/lib/X11/app-defaults/XDesktop3
/usr/lib/X11/IXI/XDesktop/rules/system/xdtsysinfo
/usr/lib/X11/IXI/XDesktop/rules/modules

NOTE: $HOME represents your home directory and hostname is the name of the machine.

Absolute pathname:	/people/fred/work/letter
Basename:	letter
Dirname:	/people/fred/work
Relative pathname:	determined by present working directory:
Working directory:	Relative pathname:
	/	people/fred/work/letter
	/people	fred/work/letter
	/people/fred	work/letter
	/people/fred/work	letter
	any other	/people/fred/work/letter

!=	-class	-eq
-ge	-gt	-le
-lt	-ne	-same
=	==	absreadlink
basename	break	canonical
cd	continue	declare
dirname	eval	exit
extension	false	fileclass
followlink	get_attribute	get_resource
join	list commands	merge
pwd	query commands	readlink
relativepath	return	sequence
split	tolower	toupper
true	unextended	variables