Solaris Common Desktop Environment: Programmer's Guide

actions.c Example Program

This section describes a simple example program, actions.c. A complete listing of actions.c is at the end of this chapter.

Loading the Database of Actions and Data Types

Before your application can invoke an action, it must initialize the Desktop Services library (which contains the action invocation API) and load the database of action and data-type definitions.

To Initialize the Desktop Services Library

Use the DtInitialize() function to initialize the Desktop Services Library.
```
DtInitialize(*display,widget,*name,*tool_class)
```
DtInitialize() uses the default Intrinsic XtAppContext. The API provides an additional function, DtAppInitialize() to use when your application must specify an app_context:
```
DtAppInitialize(app_context,*display,widget,*name, tool_class)
```

DtInitialize() Example

The following code segment shows how the example program actions.c uses DtInitialize().

To Load the Actions and Data-Typing Database

    if (DtInitialize(XtDisplay(shell), shell,

argv[0],ApplicationClass)==False) {
 			/* DtInitialize() has already logged an appropriate error msg */
         			exit(-1);
    }

Use the DtDbLoad() function to load the actions and data-typing database.

DtDbLoad(void)

DtDbLoad() reads in the action and data-typing database. This function determines the set of directories that are to be searched for database files (the database search path) and loads the *.dt files found into the database. The directory search path is based on the value of the DTDATABASESEARCHPATH environment variable and internal defaults.

To Request Notification of Reload Events

If you use DtDbLoad() in a long-lived application, it must dynamically reload the database whenever it is modified.

Use the DtDbReloadNotify()function to request notification of reload events.
```
/* Notice changes to the database without needing to restart
	 application */

  	DtDbReloadNotify(DbReloadCallbackProc, callback_proc,
	 	XTPointer, client_data);
```
Supply a callback that:
- Destroys cached database information held by the application
- Calls the DtDbLoad() function again

Callback_proc cleans up any cached database information your application is holding and then invokes DtDbLoad(). Client_data may be used to pass additional client information to the callback routine.

Checking the Actions Database

Your application accesses the database if it needs to display the icon or label for an action. Also before invoking an action, your application can check that it exists. An action is identified in the database by the action name:

ACTION action_name 
{
  ... 
}

For example, the action definition for the Calculator looks like this:

ACTION Dtcalc
{
      LABEL				Calculator
      ICON						Dtcalc
      ARG_COUNT						0 
      TYPE            COMMAND
      WINDOW_TYPE						NO_STDIO
      EXEC_STRING						/usr/dt/bin/dtcalc
      DESCRIPTION						The Calculator (Dtcalc) action runs the \
                         desktop Calculator application. 
}

The action name for the Calculator action is Dtcalc.

When an executable file has a file name that matches an action name in the existing database, that file is an action file--a representation for the underlying action. The information about the icon and label for that file are stored in the database.

To Determine Whether a Specified Action Definition Exists

Use the DtActionExists() function to determine whether a specified action definition exists.

DtActionExists(*name)

DtActionExists() checks whether the specified name corresponds to the name of an action in the database. The function returns True if name corresponds to an action name, or False if no action with that name is found.

To Obtain the Icon Image Information for a Specified Action

Use the DtActionIcon() function to obtain the icon image information.

DtActionIcon(char *action_name)

An action definition specifies the icon image used to represent the action in the definition's ICON field:

ACTION action_name
{
     ICON icon_image_base_name  
     ... 
}

DtActionIcon() returns a character string containing the value of the icon image field. If the action definition does not contain an icon field, the function returns the value of the default action icon image, Dtactn.

You then need to determine the location of the icon, and the size you want to use. Icons can exist in four sizes and are available in bitmap or pixmap form. For example, you can find the base name of the icon file from the action definition for the Calculator. You then use the base name coupled with the information given in Table 8-1 and knowledge of the location of all the icons to find the specific icon file you want.

The icon name for the calculator action is Dtcalc, but that is not the entire file name. Icon file names are based on the size of the icon. Table 8-1 shows the sizes and file-naming conventions for the desktop icons.

Table 8-1 Icon Sizes and File Names


Icon Size	Bitmap Name	Pixmap Name
16 by 16 (tiny)	`name.t.bm`	`name.t.pm`
24 by 24 (small)	`name.s.bm`	`name.s.pm`
32 by 32 (medium)	`name.m.bm`	`name.m.pm`
48 by 48 (large)	`name.l.bm`	`name.l.pm`

Note -

See "Creating Icons for the Desktop" in the Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide for more information about the desktop icon files.

For bitmaps, there is an additional file that is used as a mask, and its extension ends with _m.bm. Thus, there can be a total of three files for each size icon. Here are the icon files for the calculator:

Dtcalc.t.bm  
Dtcalc.t.pm
Dtcalc.t_m.bm  
Dtcalc.m.bm  
Dtcalc.m.pm  
Dtcalc.m_m.bm  
Dtcalc.l.bm 
Dtcalc.l.pm  
Dtcalc.l_m.bm

Note -

There are no small icons (Dtcalc.s.bm, Dtcalc.s.pm, Dtcalc.s_m.bm) for the Calculator.

DtActionIcon() returns only a base name; for the Calculator it is Dtcalc. You must choose the type (pixmap or bitmap) and size (tiny, small, medium, or large) and append the applicable extension to the base name. In addition, you must know where the file resides.

To Get the Localized Label for an Action

Use the DtActionLabel() function to get the localized label for an action.

char *DtActionLabel(char *actionName)

An action definition may include a label. The label is defined using the label_text field:

ACTION action_name {

   LABEL label_text
   ...
}

This label is used in graphical components (such as File Manager and the Application Manager) to label the action's icon. If an action definition does not include a label_text field, the action_name is used.

The value of label_text string should be used by all interface components to identify the action to the end user.

The DtActionLabel() function returns the value of the label_text field in the action definition of the action named actionName. If the label_text field does not exist, the function returns the actionName.

Invoking Actions

After your application has initialized the Desktop Services Library it can then invoke an action.

To Invoke an Action

Use theDtActionInvoke function to invoke an action.

DtActionInvoke (widget, action, args, argCount, termOpts, execHost,, 
		contexDir, useIndicator,statusUpdateCb, client_data)

DtActionInvoke() searches the action database for an entry that matches the specified action name, and accepts arguments of the class, type, and count provided. Remember that your application must initialize and load the database before invoking an action.