# Introduction to Actions and Data Types

Actions and data types are powerful components for integrating applications into the desktop. They provide a way to create a user interface for starting applications and manipulating their data files.

SAG.IntAc.div.3
SAG.IntAc.div.7

This chapter introduces the concepts of actions and data types. It describes:

- Why you may want to create actions and data types for applications.

- How actions and data types are related to each other.

- How actions and data types are related to desktop printing.

## See Also

The procedures and rules for creating actions and data types are covered in three chapters in this manual.

- SAG.dtCrA.div.1 explains how to create actions and data types using the desktop application Create Action.

  You can use Create Action to create actions and data types for most applications without having to learn the syntax rules for their definitions.

- SAG.CrAct.div.1 and SAG.CrDT.div.1 explain how to create actions and data types manually by creating and editing configuration files.

  It is necessary to create actions and data types manually when you want to use advanced features not supported by Create Action.

## Introduction To Actions

Actions are instructions written that automate desktop tasks such as running applications and opening data files. Actions work much like application macros or programming functions. Each action has a name that is used to run the action.

Once you define an action, it can be used to adapt the desktop user interface so that tasks are easier to do. The desktop provides the ability to attach user interface components such as icons, Front Panel controls, and menu items to actions.

### Uses for actions

For example, the Desktop_Tools application group in Application Manager contains icons that start various utilities.

### Action icons in the Desktop_Tools application group

Each of these icons runs an action when the icon is double-clicked. For example, here's a portion of the definition of the action that runs when the user double-clicks the icon labeled Xwd Display. The action is defined in the configuration file `/usr/dt/appconfig/types/`language`/xclients.dt`:

    ACTION Xwud
    {
     LABEL        Xwd Display
     TYPE         COMMAND
     EXEC_STRING  /usr/bin/X11/xwud -noclick -in \
                  %(File)Arg_1“Xwd File To Display:“%
     …
    }

The command in the action's `EXEC_STRING` is run when the user double-clicks the icon.

The Front Panel also uses actions. For example, here's a portion of the definition of the control labeled Terminal in the Personal Applications subpanel. The control is defined in the configuration file `/usr/dt/appconfig/types/`language`/dtwm.fp`:

    CONTROL Term
    {
     ICON         Fpterm
     LABEL        Terminal
     PUSH_ACTION  Dtterm
     …
    }

The `PUSH_ACTION` field specifies the action to run when the user clicks the control—in this case, an action named Dtterm.

Another common use for actions is in menus. Data files usually have actions in their Selected menu in File Manager. For example, XWD files (files with names ending in`.xwd` or`.wd`) have an Open action that displays the screen image by running the Xwud action.

### Open action for files of data type XWD

The actions in the
Selected menu are specified in the data type definition for XWD files. The definition is located in the configuration file `/usr/dt/appconfig/types/`language`/xclients.dt.`

    DATA_ATTRIBUTES XWD
    {
     ACTIONS  Open,Print
     ICON     Dtxwd
     …
    }

The XWD data type, and its associated Open and Print actions, are explained in SAG.IntAc.div.9.

### How Actions Create Icons for Applications

Consider the Xwd Display icon in the Desktop_Tools application group. Double-clicking this icon runs the X client `xwud`. However, this icon does not directly represent the actual `xwud` executable `/usr/bin/X11/xwud`.

The icon labeled Xwd Display appears in the application group because there is a file in that directory named `Xwud` (see SAG.IntAc.mkr.1). This file represents an underlying action with the same name—Xwud. In the action definition, the action name is the name following the `ACTION` keyword:

    ACTION Xwud
    {
     LABEL        Xwd Display
     TYPE         COMMAND
     WINDOW_TYPE  NO_STDIO
     EXEC_STRING  /usr/bin/X11/xwud -noclick -in \
                  %(File)Arg_1“Xwd File To Display:“%
     DESCRIPTION  The Xwd Display (Xwud) XwdDisplay action \
                  displays an xwd file that was created using the \
                  Xwd Capture (Xwd) action. It uses \
                  the xwud command.
    }

The file is called an action file because it represents an action. A file is an action file when it is an executable file with the same name as an action. Its icon in Application Manager (or File Manager) is called an
action icon, or
application icon, because double-clicking it starts an application.

#### Application (action) icon representing an action file

When Application Manager detects an executable file, it looks through the actions database to see if there are any actions whose names match the file name. If a match is found, Application Manager knows that the file is an action file.

The content of the action file is irrelevant; action files usually contain comments describing their desktop function.

The action file is not the same as the action definition file. The action file is a file with the same name as the action. It is used to create the application icon in File Manager or Application Manager. The action definition file is the file named name`.dt` containing the definition of the action.

Once the desktop determines that a file is an action file, the underlying action definition is used to define the appearance and behavior of the action file.

- The `EXEC_STRING` field specifies the behavior of the application icon. In the case of the Xwd Display icon, the `EXEC_STRING` specifies that the action icon runs the `xwud` X client with certain command-line arguments.

- The `LABEL` field specifies the label for the application icon.

- The `DESCRIPTION` field describes the text displayed when the user requests On Item help.

- The Xwud application icon uses the default icon image for actions because its action definition does contain an `ICON` field to specify a different image.

  In contrast, the icon labeled Compress File uses a different icon image because its underlying action definition contains an `ICON` field:

  For example:

      ACTION Compress
       LABEL  Compress File
       ICON   Dtcmprs
       …
      }

#### Icon image specified by the ICON field in the action definition

The Xwud action is called a command action because its definition contains the command (`EXEC_STRING`) to be run. The `TYPE` field in the action definition defines the action type.

Initially, the Xwd Display icon appears in the Desktop_Tools application group. However, you can create additional copies of the action icon in any directory for which you have write permission. As long as the Xwud action definition is part of the database, any executable file you create named `Xwud` will be an action file representing that action, and its icon in File Manager or Application Manager can be used to run the action.

### How Actions Use Data Files as Arguments

An
argument of a command is the thing, usually a
file, that the command acts upon. Actions can be written to accept file arguments.

For example, the `EXEC_STRING` of the Xwud action specifies that a file argument is required:

    EXEC_STRING  /usr/bin/X11/xwud -noclick -in \
                 %(File)Arg_1“Xwd File To Display:“%

The term `Arg` stands for the word argument. The syntax
`Arg_1` means the first argument, and `(File)` means that the action treats that argument as a file.

The easiest way for the user to provide a file argument is to drop a data file on the application icon. The desktop determines the path of the dropped file and substitutes it into the command line in place of the text between the `%` symbols (`%(File)Arg_1“Xwd File To Display:“%`). Thus, the command that gets executed is:

    /usr/bin/X11/xwud -noclick -in file_path

When the user double-clicks the application icon, the desktop determines from the `EXEC_STRING` that a file argument is required, and displays a dialog box prompting the user to enter a file name or path. In the case of the Xwud action, the prompt is:

    Xwd File To Display:

The file name or path supplied by the user is used as the file argument.

### Additional Uses for Actions

In addition to starting applications, actions are used throughout the desktop to create functionality in:

- The Front Panel.

  The definition for a Front Panel control includes fields that specify the action that runs when the user clicks the control or drops a file on it. For more information, see SAG.FrPC.div.34.

- Menus.

  The syntax for the Window and Workspace menu definitions allows you to specify the action to be run by a menu item. For more information, see SAG.WMCnf.div.13 and the `dtwmrc(4)` man page.

- Communication between applications.

  An application can be designed to send and receive information using a special type of action called ToolTalk message (`TT_MSG`). `TT_MSG` actions are described in the developer environment documentation for the desktop.

## Introduction to Data Types

When the user creates a new data file, the appearance and behavior of the file's icon in File Manager varies depending on the type of data file the user has created. This ability to create custom appearance and behavior for files and directories is provided by the desktop's data typing mechanism.

### What Is a Data Type?

A data type is a construct that is defined within the desktop database. For example, here is the definition of the XWD data type. The definition is in the configuration file `/usr/dt/appconfig/types/`language`/xclients.dt`:

    DATA_ATTRIBUTES XWD
    {
     ACTIONS        Open,Print
     ICON           Dtxwd
     NAME_TEMPLATE  %s.xwd
     MIME_TYPE      application/octet-stream
     SUNV3_TYPE     xwd-file
     DESCRIPTION    This file contains a graphics image in the XWD \
                    format. These files are typically created by \
                    taking snapshots of windows using the XwdCapture \
                    action. Its data type is named XWD. XWD files \
                    have names ending with `.xwd' or `.wd'.
    }
    DATA_CRITERIA XWD1
    {
     DATA_ATTRIBUTES_NAME  XWD
     MODE                  f
     NAME_PATTERN          *.xwd
    }

    DATA_CRITERIA XWD2
    {
     DATA_ATTRIBUTES_NAME  XWD
     MODE                  f
     NAME_PATTERN          *.wd
    }

Every data type definition has two parts:

`DATA_ATTRIBUTES` | Describes the appearance and behavior of the data type.
`DATA_CRITERIA`, | Specifies the rules (naming or content) for categorizing a file as belonging to that data type.

The `DATA_ATTRIBUTES_NAME` field connects the criteria to the attributes.

There can be multiple `DATA_CRITERIA` for a `DATA_ATTRIBUTE`. For example, the XWD data type has two criteria to specify two different naming criteria (`NAME_PATTERN`)—names ending with `.xwd` or `.wd`.

### How Data Types Connect Data Files to Actions

Consider the XWD data type. The user creates an XWD-type file by giving the file one of two file-name suffixes (extensions): `.xwd` or`.wd`. The desktop uses the file name as the criteria for designating a file as that type.

The XWD data type supplies each file of that data type with:

- A unique icon image that helps users recognize the data files.

- On Item help that tells you about the data type.

- A customized Selected menu in File Manager containing the actions Open and Print. The Open action for XWD files runs the Xwud action.

#### Running Actions from the Selected Menu

The Selected menu in File Manager is active only when a file or directory is selected. The commands at the bottom of the Selected menu depend on the data type. For example, if an XWD file is selected, the Selected menu includes the items Open and Print.

The `ACTIONS` field in the data type definition specifies the commands added to the bottom of the data type's Selected menu.

    DATA_ATTRIBUTES XWD
    {
            ACTIONS  Open,Print
            …
    }

The contents of the Selected menu depends on the data type. However, many different data types provide an Open action—that is, when you select a file of that particular data type in File Manager and display the Selected menu, you see an Open command.

##### The Selected menu for an XWD file

The
Open action usually runs the application with which the data file is associated. For example, opening an XWD file runs the Xwud action, which in turn runs the xwud X client to display the screen image. In other words, for the XWD data type, the Open action is synonymous with the Xwud action. Likewise, opening a file of data type TEXTFILE runs the Text Editor, and opening a BM (bitmap) or PM (pixmap) file runs Icon Editor.

The ability to create a variety of Open actions that do different things uses two features of action definitions:

- Action mapping.

  Action mapping lets you create an action that runs another action, rather than directly running a command. For example, you can create an Open action that maps to (runs) the Xwud action.

- Data-type restrictions on an action.

  Action definitions can include an `ARG_TYPE` field that limits the action to certain data types. For example, you can specify that the Open action that maps to the Xwud action applies only to files of data type XWD.

Here is the definition of the action that maps the Open action to the Xwud action for the XWD data type. It is located in the database configuration file `/usr/dt/appconfig/types/language/xclients.dt`:

    ACTION Open
    {
     LABEL       Open
     ARG_TYPE    XWD
     TYPE        MAP
     MAP_ACTION  Xwud
    }

The `TYPE` field specifies that this is a map action; the `MAP_ACTION` field specifies this action runs the Xwud action. The `ARG_TYPE` field specifies that this action applies only to files whose data type is XWD.

Compare the previous definition of the Open action to the next definition, which appears in the database file `/usr/dt/appconfig/types/language/dt.dt`:

    ACTION Open
    {
     LABEL       Open
     ARG_TYPE    BM
     TYPE        MAP
     MAP_ACTION  Dticon
    }

This definition applies to files of data type (`ARG_TYPE`) BM (bitmap files). The definition maps the Open action to the Dticon action, which runs Icon Editor.

####
Defining the Double-Click Behavior of the Data Type

The data type's double-click behavior is defined by the first entry in the `ACTIONS` field. For example, for the XWD data type, the double-click behavior is to run the Open action, which in turn runs the Xwud action.

#### Dropping a Data File on an Action Icon

When the user drops a data file on an action icon, the system runs the action using that data file as the argument for the action (see SAG.IntAc.mkr.4).

For example, when an XWD data file is dropped on the Xwd Display icon, the Xwud action is run using the data file argument. This runs the `xwud` X client with that data file.

### Creating Desktop Printing for a Data Type

Desktop printing provides these ways to print a data file:

- Using the Print command, if available, in the File Manager Selected menu.

- Dropping a data file on a desktop printer drop zone (the Front Panel Printer control or a printer icon in Print Manager).

In addition to desktop printing, many applications provide a way to print from within the application.

Desktop printing uses actions named Print. Print, like Open, is an action name that is used for many different types of data. Therefore, Print actions use action mapping and the `ARG_TYPE` field to customize printing for each data type.

For example, here is the Print action for the XWD data type. The definition is located in `/usr/dt/appconfig/types/`language`/xclients.dt`:

    ACTION Print
    {
     LABEL       Print
     ARG_TYPE    XWD
     TYPE        MAP
     MAP_ACTION  NoPrint
    }

This Print action, specific to XWD files, is mapped to a NoPrint action. NoPrint is a special action defined in `/usr/dt/appconfig/types/`language`/dt.dt`. The
NoPrint action displays a dialog box telling the user that this data type cannot be printed.

Compare the XWD Print action with the following Print action for PCL files:

    ACTION Print
     LABEL       Print
     ARG_TYPE    PCL
     TYPE        MAP
     MAP_ACTION  PrintRaw
    }

The PrintRaw action, defined in the configuration file `/usr/dt/appconfig/types/`language`/print.dt`, contains the command line for printing the PCL files.

    ACTION PrintRaw
    {
     TYPE         COMMAND
     WINDOW_TYPE  NO_STDIO
     EXEC_STRING  /usr/dt/bin/dtlp -w %(File)Arg_1%
    }