Creating an object manually

To create an object on the Desktop, perform the following steps.

1. Create an object directory with the desired name, followed by an .obj extension.

2. Select pixmaps to represent the object and copy them to the object directory, using one of the following filenames:
   
   picture.px
   open.px
   s_picture.px
   s_open.px

3. Decide which mouse actions or triggers are to be applied to the object.

4. For each trigger, write an object script that will perform some Desktop or system action.

5. Place each object script in the file specified by its corresponding trigger name (for example, activate for the activate trigger).

Step 1: Creating the object directory

Every object has a corresponding object directory. This directory contains all of the information that defines the object's behavior.

The object directory should be named by appending the extension .obj to the desired name for the object. For example, an object called ``Compress'' has an object directory named Compress.obj.

The object's title is specified in the name of the corresponding object directory. Or you can define an object's title by storing it in a file called title, which you should locate in a language subdirectory, ll_TT, within the object directory. ll is a two-character code for the language (as defined by the ISO 639 standard) and TT is a two-character code for territory (as defined by the ISO 3166 standard). By default, en_US is used.

An object only appears on the Desktop or a desktop window if it is explicitly dragged onto the Desktop or a desktop window using the Deskshell command get_out or if the object's parent directory is open. For example, applications/My.obj is visible only if either the directory applications is open or My.obj has been dragged out onto the Desktop or a desktop window.

If you wish to include an object Desktop-wide, you should create it or, if it already exists, use an Applications or Tools directory and place the object directory there. The main Desktop's desktop rule file can then be configured so that this Tools directory appears on it. The current default directory for the applications directory is /usr/lib/X11/XDesktop3/apps and the tools directory is /usr/lib/X11/XDesktop3/tools.

See also:

• deskcommands(XC) manual page for more information on Deskshell commands

Step 2: Selecting an icon

When defining an object, first consider what its icon or pictorial representation will look like. The icon for the object can be one of many pre-defined picture files or a custom-made icon.

By default, objects can contain four pixmap files to use for an icon. These are:

picture.px

a large [64x64] image for the icon when not active. This is the only file that must be present.

s_picture.px

a small [32x32] image for the icon when not active

open.px

a large [64x64] image for the icon when active

s_open.px

a small [32x32] image for the icon when active

local_large

your own large [64x64] color icons

xdt_large

the Desktop's default large [64x64] color icons

xdt_small

the Desktop's default small [32x32] color icons

xdt_c_large

large [32x32] cursors

xdt_c_small

small [16x16] cursors

Picture files can be in either pixmap or bitmap format. Pixmap format is a color bitmap format defined using standard ASCII characters. The resulting files can be created and edited using a standard text editor or a pixmap editor.

Bitmap is a monochrome format and should only be used if backward compatibility with SCO Open Desktop, Release 1.1 is required.

To create a custom-made icon for an object, the best approach is to start with an existing picture file and then edit it as follows:

1. Copy an existing picture file from one of the preceding directories or the blank picture file blank.px into the object directory and rename it appropriately, as described above.

2. Change to the object directory. Edit the picture using a text or pixmap editor and save your changes.

Step 3: Selecting trigger actions

The action of pointing at an icon with the mouse pointer and performing an action such as double-clicking is referred to as ``triggering'' the icon. Triggers are used to execute different Desktop and/or system actions and tasks. When an object is triggered, it performs certain actions on the Desktop or the system, depending the trigger type.

A trigger is either a click, a sequence of clicks only, or a sequence of clicks followed by a hold or drag. You can trigger icons on the Desktop in three ways: static triggers, hold triggers and drag triggers.

Clicking twice in succession without moving the mouse pointer is called either double-clicking, activating the icon, or a ``static'' trigger. Dragging one or more icons and dropping them on to another icon is called a ``drag and drop'' or a ``dynamic'' trigger. Pressing a mouse button and holding it down while the pointer is over an object is referred to as a ``hold'' trigger.

The notation for the different triggers is based on the trigger type and the mouse button used. The following are the pre-defined Desktop triggers:

• Static triggers:

  
  select

  single-click on an icon picture

  
  alt_select

  single-click on an icon picture with mouse button 2

  
  rename

  single-click on an icon title

  
  alt_rename

  single-click on an icon title with mouse button 2

  
  activate

  double-click on an icon

  
  alt_activate

  double-click on an icon with mouse button 2

  
  deselect

  single-click on a window background

  
  report

  double-click on a window background

  
  alt_report

  double-click on window background with mouse button 2

  
  s*

  matches any static trigger

• Dynamic triggers:

  
  drop

  drop one or more icons on an icon or window background

  
  alt_drop

  drop one or more icons on an icon or window background with mouse button 2

  
  d*

  matches any drag trigger

• Hold triggers:

  
  menu

  hold mouse button 3 on an icon picture or title

  
  popup_menu

  hold mouse button 3 on a window background

  
  h*

  matches any hold trigger

See also:

• ``Mapping mouse triggers for the Panorama (xdt3) Desktop'' for information on mapping your own triggers or changing the existing ones

Step 4: Writing trigger scripts

After the triggers to be applied to the objects are determined, the Desktop or operating system actions and tasks that are to occur after each trigger action must be defined.

The Deskshell command language is used to to define the actions that occur when the icon is triggered. Deskshell scripts written explicitly for objects are referred to as object scripts.

Deskshell is a command language, complete with a flexible range of control structures and a wide range of commands. You can specify regular UNIX operating system commands within Deskshell scripts. However, it is recommended that you learn how to use the Deskshell commands and scripts.

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.

See also:

• ``Writing Deskshell commands''

Step 5: Naming trigger scripts

The final step involves naming the object scripts and placing them in the proper location.

After an object script is written in Deskshell, it must be placed in a file. Filenames correspond directly to the trigger names (i.e., activate for an activate trigger and drop for a drop trigger).

Trigger files should be placed directly in the object directory, not within any language subdirectory.

Any text that you intend to display to the user should be represented by variable names, and the definitions for these variables placed in the text file within the object directory's language subdirectory. For example:

   msg1='You have activated this object'
   msg2='You have dropped an icon on this object'

See also:

• xdt3(XC) manual page

• deskshell(XC) manual page

• deskcommands(XC) manual page