Creating an Action Manually: General Steps

This section explains how to create a configuration file for an action definition.

Configuration Files for Actions

Configuration files containing action definitions must meet these requirements:

The files must use the naming convention name.dt
The files must be located on the database (actions and data types) search path. The default search path is:
Personal actions
HomeDirectory/.dt/types
System-wide actions
/etc/dt/appconfig/types/language
Built-in actions
/usr/dt/appconfig/types/language. You should not use this directory.

For information on modifying the actions/data types search path, see “Setting the Value of a Search Path”.

To Create an Action Manually

Open an existing database file or create a new one. See the previous section, “Configuration Files for Actions”.

Create the action definition using the syntax:

ACTION action_name
{
 TYPE action_type  action_field
 ...
}

where:

action_name	Name used to run the action.
action_type	COMMAND (default), MAP, or `TT_MSG.`
action_field	One of the required or optional fields for this type of action. All fields consist of a keyword and a value. Many of the action fields are covered in this chapter. For more information, see the dtactionfile(4) man page.

Save the file.
If you want the action icon to have a unique image, create the icons for the action. The default location for icons is:
- Personal icons: HomeDirectory/.dt/icons
- System-wide icons: /etc/dt/appconfig/icons/language. The default language is C.
  For more information, see “Specifying the Icon Used by a Control”.
Double-click Reload Actions in the Desktop_Tools application group.
Create an action file for the action. The action file creates an icon in File Manager or Application Manager that represents the action. (If the action is written to start an application, the icon is called an application icon.)
To create the action file, create an executable file with the same name as action_name. You can put the file in any directory to which you have write permission. You can create as many action files as you like.

Example of Creating a COMMAND Action

The following steps create a personal action that starts a fax application on remote system AppServerA. The command for starting the fax application is:

/usr/fax/bin/faxcompose [filename]

Create the file HomeDirectory/.dt/types/Fax.dt.

Put the following action definition into the file:

ACTION FaxComposer
{
 TYPE         COMMAND
 ICON         fax
 WINDOW_TYPE  NO_STDIO
 EXEC_STRING  /usr/fax/bin/faxcompose -c %Arg_1%
 EXEC_HOST       AppServerA
 DESCRIPTION  Runs the fax composer
}

The WINDOW_TYPE and EXEC_STRING fields describe the behavior of the action.

`WINDOW_TYPE`	The `NO_STDIO` keyword specifies that the action does not have to run in a terminal emulator window. See “Specifying the Window Support for the Action”.
`EXEC_STRING`	The syntax `%Arg_1%` accepts a dropped file. If the action icon is double-clicked, the action opens an empty fax composer window. See “Building the Execution String for a COMMAND Action”.

Save the file.
Use Icon Editor to create the following image files in the HomeDirectory/.dt/icons directory:
- fax.m.pm, size 32 by 32 pixels
- fax.t.pm, size 16 by 16 pixels
Double-click Reload Actions in the Desktop_Tools application group.
Create an executable file named FaxComposer in a directory to which you have write permission (for example, your home directory).

Example of Creating a MAP Action

Suppose most of the files you fax are created with Text Editor and are of data type TEXTFILE (files named *.txt).

These steps add a ``Fax'' menu item to the data type's Selected menu.

Open the file HomeDirectory/.dt/types/Fax.dt that was created in the previous example.

Add this map action definition to the file:

ACTION Fax
{
 ARG_TYPE    TEXTFILE
 TYPE        MAP
 MAP_ACTION  FaxComposer
}

Save the file.
Copy the data attributes definition for TEXTFILE from /usr/dt/appconfig/types/language/dtpad.dt to a new file HomeDirectory/.dt/types/textfile.dt. Add the Fax action to the ACTIONS field.
DATA_ATTRIBUTES TEXTFILE { ACTIONS Open,Print,Fax ICON Dtpenpd ... }
Save the file.
Open Application Manager and double-click Reload Actions in the Desktop_Tools application group.

To Reload the Actions/Data Types Database

In order for new or edited action definitions to take effect, the desktop must reread the database.

Open the Desktop_Tools application group and double-click Reload Actions.
Or, execute the command:
dtaction ReloadActions

ReloadActions is the name of the action whose icon is labeled ``Reload Actions.''

The actions database is also reread when the user:

Logs in
Restarts the Workspace Manager
Saves an action in the Create Action window by choosing Save from the File menu

Creating an Action File (Icon) for an Action

An action file is a file created to provide a visual representation of the action in File Manager or Application Manager.

Figure 10-1 Action files (also called action icons or application icons) in Application Manager

Since an action file's icon represents an action, it is sometimes called an action icon. If the underlying action starts an application, the action file icon is called an application icon.

Double-clicking the action icon runs the action. The action icon may also be a drop zone.

To Create an Action File (Action Icon)

Create an executable file with the same name as the action name. The content of the file does not matter.

For example, if the action definition is:

ACTION  MyFavoriteApp
{
 EXEC_STRING    Mfa -file %Arg_1%
 DESCRIPTION    Runs MyFavoriteApp
 ICON           Mfapp
}

then the action file would be an executable file named MyFavoriteApp. In File Manager and Application Manager, the MyFavoriteApp file would use the icon image Mfapp.size.type. Double-clicking MyFavoriteApp's icon would run the action's execution string, and the icon's On Item help would be the contents of the DESCRIPTION field (Runs MyFavoriteApp).

Action Labels

If the action definition includes the LABEL field, the action file will be labeled in File Manager and Application Manager with the contents of this field rather than the file name (action_name). For example, if the action definition includes:

ACTION  MyFavoriteApp
{
 LABEL      Favorite Application
 ...
}

then the action icon will be labeled ``Favorite Application.''

Specifying the Icon Image Used by an Action

Use the ICON field to specify the icon used in File Manager and Application Manager for the action icons created for the action.

If you do not specify an icon, the system uses the default action icon image files /usr/dt/appconfig/icons/language/Dtactn.*.

Figure 10-2 Default action icon image

The default action icon can be changed using the resource:

*actionIcon: icon_file_name

where icon_file_name can be a base name or absolute path.

The value of the ICON field can be:

A base file name.
The base file name is the name of the file containing the icon image minus the file-name suffixes for size (m and t) and image type (bm and pm). For example, if files are named GameIcon.m.pm and GameIcon.t.pm, use GameIcon.
If you use the base file name, the icon files must be placed in a directory on the icon search path:
- Personal icons: HomeDirectory/.dt/icons
- System-wide icons: /etc/dt/appconfig/icons/language
An absolute path to the icon file, including the full file name.
You should use the absolute path only if the icon file is not located on the icon search path. For example, if icon file GameIcon.m.pm is placed in the directory /doc/projects, which is not on the icon search path, the value of the ICON field would be /doc/projects/GameIcon.m.pm.

Table 10-1 “Icon Names and Sizes for Action Icons” lists icon sizes you should create and the corresponding file names.

Table 10-1 Icon Names and Sizes for Action Icons

`Size in Pixels`	`Bitmap Name`	`Pixmap Name`
48 by 48	`name``.l.bm`	`name``.l.pm`
32 by 32	`name``.m.bm`	`name``.m.pm`
16 by 16	`name``.t.bm`	`name``.t.pm`

To Modify an Existing Action Definition

You can modify any of the actions available on your system, including built-in actions.




	NOTE: Use caution when modifying the built-in action database. The built-in actions are designed to work well with the desktop applications.

Locate the definition of the action you want to modify.
The default locations for action definitions are:
- Built-in actions: /usr/dt/appconfig/types/language
- System-wide actions: /etc/dt/appconfig/types/language
- Personal actions: HomeDirectory/.dt/types
  Your system might include additional locations. To see a list of the locations your system uses for actions, execute the command:
  dtsearchpath -v
  Your system uses the directories listed under DTDATABASESEARCHPATH.
If necessary, copy the text of the action definition to a new or existing file in one of these directories:
- System-wide actions: /etc/dt/appconfig/types/language
- Personal actions: HomeDirectory/.dt/types
  You must copy built-in actions, since you should not edit files in the /usr/dt/appconfig/types/language directory.
Edit the action definition. When you are done, save the file.
Double-click Reload Actions in the Desktop_Tools application group.

Precedence in Action Definitions

When the user invokes an action, the system searches the database for a matching action name. When more than one action exists with that name, the system uses precedence rules to decide which one to use.

If no other precedence rules apply, the precedence is based on the location of the definition. The following list is ordered from higher to lower precedence:
- Personal actions (HomeDirectory/.dt/types)
- System-wide local actions (/etc/dt/appconfig/types/language)
- System-wide remote actions (hostname:/etc/dt/appconfig/types/language). The remote hosts searched are those listed in the application search path.
- Built-in actions (/usr/dt/appconfig/types/language)
Within a given directory, the *.dt files are read in alphabetical order.
Actions restricted by ARG_CLASS, ARG_TYPE, ARG_MODE, or ARG_COUNT have precedence over unrestricted actions. (The default for these four fields is *.)
Where more than one restriction applies, the precedence order from high to low is:
- ARG_CLASS
- ARG_TYPE
- ARG_MODE
- ARG_COUNT
Where more than one restricted ARG_COUNT exists, the precedence order from high to low is:
- Specific integer value n
- <n
- >n
- *

For example, consider the following portions of action definitions:

ACTION EditGraphics
# EditGraphics-1
{
 ARG_TYPE    XWD
 ...
}
ACTION EditGraphics
# EditGraphics-2
{
 ARG_COUNT      0
 ...
}
ACTION EditGraphics
# EditGraphics-3
{
 ARG_TYPE    *
    ...
}

Double-clicking the EditGraphics action icon starts EditGraphics-2 because no argument is provided and ARG_COUNT 0 has precedence. When an XWD-type file argument is provided, EditGraphics-1 is used because it specified the XWD ARG_TYPE. EditGraphics-3 is used for all other file arguments.