Solaris Common Desktop Environment: Advanced User's and System Administrator's Guide

Defining Front Panel Controls

The user can create personal controls by dropping icons on the Install Icon controls.

While this provides easy customizability, the functionality it provides is a subset of the capabilities of Front Panel controls. For example, a control created using the Install Icon control cannot:

Provide animation

Display a client window

Change appearance when an event occurs (for example, upon receiving new mail)

This section describes how to manually create Front Panel controls.

For reference information on the syntax of Front Panel controls, see the dtfpfile(4X) man page.

Front Panel Control Definitions

The structure of a Front Panel control definition is:

CONTROL control_name
 {
   TYPE            control_type
   CONTAINER_NAME  value
   CONTAINER_TYPE  value
   other fields defining appearance and behavior
 }

Control Types

The TYPE field in the control definition specifies the basic behavior of the control.

Control TYPE: Control Behavior
icon (Default).: The control will run a specified action when the user clicks the control or drops a file on it.
blank: Placeholder used to adjust spacing of controls.
busy: Busy light. The control blinks (toggles images) when an action is invoked
client: A client window in the Front Panel.
clock: Clock.
date: Displays the current date.
file: Represents a file. Choosing the control runs the default action for the file.

To Create a New Control

This section describes the general steps for defining a control and describes how to create various types of controls.

If the control will have a PUSH_ACTION and/or DROP_ACTION, create the action definitions. These are the actions that run when the user clicks the control or drops a file on it.

Create the icon image files for the control.

For information about icon sizes, names, and locations, see Icon Image Files.

Create a new Front Panel configuration file in:
- System-wide: /etc/dt/appconfig/types/language/*.fp
- Personal: HomeDirectory/.dt/types/*.fp

Add the control definition to the file.

Save the file.

Choose Restart Workspace Manager from the Workspace menu.

Creating a Control that Runs an Action When Clicked

Use these fields to define the control's behavior:

TYPE: Set to icon

PUSH_ACTION: Specifies the name of the action to be run

For example, the following control, which will be put in the Personal Applications subpanel, runs a game the user has acquired:

CONTROL Ball
 {
 	TYPE							icon
 	CONTAINER_NAME				PersAppsSubpanel
 	CONTAINER_TYPE				SUBPANEL
 	ICON							ball
 	PUSH_ACTION					RunBallGame
 	HELP_STRING					"Choose this control to play Ball."
 }

The following control will be located in the upper left corner of the switch. It starts an action named CutDisp.

CONTROL StartCutDisp
 {
   TYPE							icon
   CONTAINER_NAME			Switch
   CONTAINER_TYPE			SWITCH
   POSITION_HINTS			first
   ICON							cutdisp
   HELP_STRING				"Choose this control to run cutdisp."
   PUSH_ACTION				CutDisp
 }

Creating a Control that Opens a File

Use these fields to define the control's behavior:

TYPE: Set to file
FILE_NAME: Specifies the path of the file to be opened

PUSH_ACTION: Set to Open

There must be an Open action defined for the data type of the file.

For example, the following control will be located on the far right side of the Main Panel. It starts Text Editor with the data file /users/ellen/PhoneList.txt. The Open action for *.txt files is part of the default action database.

CONTROL EditPhoneList
 {
    TYPE                file
    FILE_NAME           /users/ellen/PhoneList.txt
    CONTAINER_NAME      Top
    CONTAINER_TYPE      BOX
    POSITION_HINTS      last
    ICON                PhoneBook
    HELP_STRING         "This control displays Ellen's phone list."
    PUSH_ACTION         Open
 }

Creating a Control that Behaves as a Drop Zone

Use the DROP_ACTION field to specify the action that runs when the user drops a file on the control. The action must be capable of accepting a file argument.

Frequently, a control definition includes both a PUSH_ACTION and DROP_ACTION field. You can use the same action for the push and drop action.

For example, the following control, located in the Personal Applications subpanel, runs the X client xwud, which takes a file argument.

CONTROL Run_xwud
 {
 	CONTAINER_NAME				PerAppsSubpanel
 	CONTAINER_TYPE				SUBPANEL
 	POSITION_HINTS				2
 	ICON							XwudImage
 	PUSH_ACTION					RunXwud
 	DROP_ACTION					RunXwud
 }

Creating a Control that Monitors a File

Use these fields to define the control's behavior:

TYPE: Specify one of the following values:

icon—use this type if you want to specify a PUSH_ACTION and/or DROP_ACTION for the control.

file—use this type if you want the control, when chosen, to behave like the file when the file's icon is double-clicked in File Manager.

ICON and ALTERNATE_ICON: Describe the images used to indicate the non-changed and changed state of the monitored file.

MONITOR_TYPE: Describes the conditions causing the image to change. Use one of the following values:

mail—the control will change appearance when information is added to the file.

file—the control will change when the specified file becomes non-empty.

FILE_NAME: Specifies the file to be monitored.

For example, the following control looks for the presence of a file named meetings that you expect to be transferred to your system using anonymous ftp. The control is placed at the top of the Personal Applications subpanel.
```
CONTROL MonitorCalendar
 {
 	TYPE							file
 	CONTAINER_NAME				PersonalApps
 	CONTAINER_TYPE				SUBPANEL
 	POSITION_HINTS				first
 	FILE_NAME					/users/ftp/meetings
 	MONITOR_TYPE				file
 	ICON							meetingsno
 	ALTERNATE_ICON				meetingsyes
 }
```

Creating a One-Instance (Toggle) Control

A one-instance control checks to see whether the process started by the PUSH_ACTION is already running. If the process is not running, the PUSH_ACTION is run. If the process is already running, the window is moved to the top of the window stack in the current workspace.

Use these fields to define the control's behavior:

PUSH_RECALL: Set to True.

CLIENT_NAME: Specifies the name of the client to the control.

The value of CLIENT_NAME must match the first string (res_name) in the WM_CLASS property on the application's top-level window. For more information, see the xprop(1) man page.

PUSH_ACTION: Describes the action run when the user clicks the control.

For example, the following control runs one instance of an application whose action is named MyEditor.

CONTROL MyEditor
 {
 	TYPE							icon
 	CONTAINER_NAME				Top
 	CONTAINER_TYPE				BOX
 	POSITION_HINTS				15
 	PUSH_RECALL					True
 	CLIENT_NAME					BestEditor
 	PUSH_ACTION					StartMyEditor
 	ICON							MyEd
 }

To Create a Client Window Control

A client window control is an application window embedded in the Front Panel. For example, you can put a system load meter in the Front Panel by creating an xload client window control.

Define the control.

Use these fields to define the control's behavior:
- TYPE: Set to client.
- CLIENT_NAME: Specifies the client to be started.
  
  The value of CLIENT_NAME must match the first string (res_name) in the WM_CLASS property on the application's top-level window. For more information, see the xprop(1) man page.
- CLIENT_GEOMETRY: Specifies the size, in pixels, needed for the client's Front Panel window.
  
  The xwininfo(1) man page describes how to find out the size of a window in pixels.

Choose Restart Workspace Manager from the Workspace menu.

Start the client from a terminal emulator command line.

For example, the following control displays a 30 × 20 pixel load meter.
```
CONTROL LoadMeter
 {
 	TYPE							client
 	CONTAINER_NAME				Top
 	CONTAINER_TYPE				BOX
 	CLIENT_NAME					xload
 	CLIENT_GEOMETRY			30x20
 }
```
If the client is not saved and restored between sessions, you may want to configure the control to start the client when the user clicks it. For example, you can configure the LoadMeter control to start xload by adding the following line to the definition:
```
PUSH_ACTION				StartXload
```
and creating the action:
```
ACTION StartXload
 {
 	WINDOW_TYPE				NO_STDIO
 	EXEC_STRING				/usr/contrib/bin/X11/xload
 }
```

To Animate a Control

You can attach an animation sequence to be used when the user chooses the control or drops an object on it.

In order to have an animation sequence, a control must:

Be type icon
Have a PUSH_ACTION or DROP_ACTION

Specify the animation sequence using the ANIMATION component:
```
	ANIMATION animation_name
 	{
 		ANIMATION	icon1				[milisecond_delay]
 		ANIMATION	icon2				[milisecond_delay]
 		…
 	}
```
where icon1, icon 2, etc. are the names of icons, and milisecond_delay is the time delay between animation icons in milliseconds. The default time delay is 200 milliseconds.

Add the PUSH_ANIMATION and/or DROP_ANIMATION fields to the control definition. The value is the name of the ANIMATION sequence.

For example, the following lines animate a control that starts the BestEditor application. The time delay between icons is 300 milliseconds. The example assumes you've created icon files frame1, frame2, etc.
```
CONTROL BestEditor
 {
 	…
 	PUSH_ANIMATION BestEdAnimation
 	…
 }
```
```
 ANIMATION BestEdAnimation
 {
 	frame1			300
 	frame2
 	…
 }
```

Providing On Item Help for Front Panel Controls

There are two ways to provide help for a control:

Providing a help string in the control definition.

The help string is displayed in the help viewer when the user invokes on-item help for the control. The help string cannot include formatting (such as headings) or links.

To provide a help string, specify it in the control definition:
```
	HELP_STRING   			 help_string
```

Specifying a help topic in a registered help volume.

A help topic is information authored using the full capabilities of the help system. Authoring a help topic requires you to use the desktop Help Developer's Kit.

To provide a help topic, specify the help volume and topic ID in the control definition:
```
	HELP_VOLUME				help_volume_name
 	HELP_TOPIC				topic_id
```