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

Chapter 15 Advanced Front Panel Customization

Users can customize the Front Panel using its pop-up menus and the Install Icon controls in the subpanels.

This chapter covers customizing the Front Panel by creating and editing configuration files.

Front Panel Configuration Files

The Front Panel is defined in a database of configuration files.

The configuration files provide a way to customize the Front Panel. Certain modifications can only be done by editing a configuration file, including:

To provide maximum flexibility in configuring the panel, these files can be personal, system-wide, or located on other systems.

The Front Panel is created and managed by the Workspace Manager.

Default Front Panel Configuration File

The default Front Panel is defined in the Front Panel configuration file /usr/dt/appconfig/types/language/dtwm.fp.

This file should not be altered.

Search Path for Front Panel Configuration Files

The Front Panel definition can be distributed among any number of files located locally or on remote systems.

Files used to define the Front Panel must meet these requirements:

The default actions database search path includes these directories, searched in the following order:

Personal customizations—HomeDirectory/.dt/types

System-wide customizations—/etc/dt/appconfig/types/language

Built-in panel and controls—/usr/dt/appconfig/types/language

An additional directory, HomeDirectory/.dt/types/fp_dynamic, is used for personal customizations made with the user interface. Do not use this directory for manual customizations.

The actions database search path may include additional directories added to configure the system for networking. In particular, additional remote locations are added when the system is configured to access an application server. For more information, see Database (Action/Data Types) Search Path.

How the Front Panel Is Assembled: Precedence Rules

The Front Panel is assembled from all the configuration files located on the actions database search path.

Where there is a conflict between components of the definition, precedence rules determine which definition is used. Two components are in conflict with one another when they:

The Front Panel uses the following precedence rules:

Dynamically Created Front Panel Files

When the user customizes the Front Panel using the Install Icon control and pop-up menus, files are written to the directory HomeDirectory/.dt/types/fp_dynamic.

The Front Panel creates an additional file, HomeDirectory/.dt/sessions/dtwmfp.session, that is used to save and restore the state of the customized Front Panel for each session.

Administering User Interface Customizations

Users can use the pop-up menus and Install Icon controls of Front Panel controls to extensively customize the Front Panel.

This section describes how to:

To Prevent Personal Customizations

  1. If the control is a built-in control, copy its definition from /usr/dt/appconfig/types/language/dtwm.fp to /etc/dt/appconfig/types/language/name.fp.

  2. Add the following line to the control definition:

    	LOCKED   True

To Restore a Deleted Control or Subpanel

The Restore Front Panel action in the Desktop_Tools application group removes all Front Panel customizations made with the user interface. Users can use this action to remove all their personal customizations made with the Front Panel's pop-up menus.

Use the following procedure to restore an individual control.

    In the HomeDirectory/.dt/types/fp_dynamic directory, remove the file that was created when the user deleted the control. The control will have the same name as the original control that was deleted.

For example, if the user deleted the Icon Editor control, a file in the fp_dynamic directory will contain:

	CONTROL IconEditor
{
		…
  	DELETE   True
	}

When the user deletes a subpanel, a separate dynamic file is created for the subpanel and for each control in the subpanel.

Organization of the Front Panel Definition

The Front Panel is built by assembling definitions for its components. Each of these components has required syntax that defines where the component is placed in the Front Panel, what the component looks like, and how it behaves.

Front Panel Components

Figure 15–1 Front Panel components

Graphic

The Front Panel is assembled from the outside inward:

General Syntax of the Front Panel Definition

Each component in the Front Panel is defined separately using the syntax:

COMPONENT name
 {
   KEYWORD       value
   KEYWORD       value
   …
 }

Some keywords are required, others are optional. For more information, see the dtfpfile(4X) man page.

PANEL Definition

The PANEL is the top-level component. Its definition includes:

BOX Definitions

A BOX definition describes:

CONTROL Definitions

A CONTROL definition describes:

SUBPANEL Definitions

A SUBPANEL definition describes:

SWITCH Definition

The SWITCH definition describes:

Modifying the Main Panel

The Main Panel is the Front Panel window, excluding the subpanels.

Figure 15–2 Main Panel containers

Graphic

Modifications you can make include:

To Add a Control to the Main Panel

  1. Create a Front Panel configuration file:

    • System-wide: /etc/dt/appconfig/types/language/*.fp

    • Personal: HomeDirectory/.dt/types/*.fp

  2. Define the control in the file.

    Use the CONTAINER_NAME and CONTAINER_TYPE fields to specify the container for the control:

    CONTAINER_NAME  Top
     	CONTAINER_TYPE  BOX

    Use POSITION_HINTS to specify the left-to-right placement of the control. Since customizations have precedence over built-in controls, the new control will “bump” the existing control with that position one position to the right.

  3. Save the configuration file.

  4. Create an icon for the Front Panel control.

    See Specifying the Icon Used by a Control.

  5. Choose Restart Workspace Manager from the Workspace menu.

    For example, the following control definition placed in the file /etc/dt/appconfig/types/language/audio.fp inserts an audio application control between the Clock and Calendar controls.

    CONTROL AudioApplication
     {
      TYPE             icon
      CONTAINER_NAME   Top
      CONTAINER_TYPE   BOX
      ICON             AudioApp
      POSITION_HINTS   2
      PUSH_ACTION      StartAudioApplication
      PUSH_RECALL      true
     }

To Remove a Control

  1. Create a Front Panel configuration file:

    • System-wide: /etc/dt/appconfig/types/language/name.fp

    • Personal: HomeDirectory/.dt/types/name.fp

  2. Copy the definition of the control you want to delete to the new file.

    If the control is built-in, its definition is in /usr/dt/appconfig/types/language/dtwm.fp.

    You do not need to copy the entire definition. However, the portion you copy must include the fields CONTAINER_NAME and CONTAINER_TYPE.

  3. Add the DELETE field to the definition:

    	DELETE			True
  4. Save the configuration file

  5. Choose Restart Workspace Manager from the Workspace menu.

    For example, the following control definition placed in the file /etc/dt/appconfig/types/language/TrashCan.fp removes the Trash Can control from the Front Panel.

    CONTROL Trash
     {
      CONTAINER_NAME  Top
      CONTAINER_TYPE  BOX
      DELETE          True
     }

To Modify a Control

Use this procedure when you need to modify a control definition—for example, to change its icon image.

  1. Copy the entire control definition from /usr/dt/appconfig/types/language/dtwm.fp to:

    • System-wide: /etc/dt/appconfig/types/language/name.fp

    • Personal: HomeDirectory/.dt/types/name.fp.

  2. Edit the field you want to change. You can also add additional fields.

  3. Save the file

  4. Choose Restart Workspace Manager from the Workspace menu.

To Interchange the Position of Controls

  1. Copy the control definitions for the controls whose positions you want to change from /usr/dt/appconfig/types/language/dtwm.fp to:

    • System-wide: /etc/dt/appconfig/types/language/name.fp

    • Personal: HomeDirectory/.dt/types/name.fp.

      You must copy the entire control definition for each control to be moved.

  2. Interchange the values of the POSITION_HINTS fields of the control definitions.

  3. Save the file

  4. Choose Restart Workspace Manager from the Workspace menu.

    For example, the following definitions placed in a file /etc/dt/appconfig/types/C/MailHelp.fp interchange the positions of the Mail and Help Manager controls and lock these controls against personal changes.

    CONTROL Mail
     {
     	POSITION_HINTS					12
     	LOCKED							True
     	…the rest of the control definition
     }
     
    CONTROL Help
     {
     	POSITION_HINTS					5
     	LOCKED							True
     	…the rest of the control definition
     }

To Replace a Front Panel Control

    Create another control definition with the same:

Specifying the Icon Used by a Control

The control definition's ICON field defines the icon image used for the control.

The value of the ICON field can be:

Creating and Modifying Subpanels

Users can create and modify subpanels using the Front Panel pop-up menus.

This section discusses how to provide system-wide customization, which requires you to modify the Front Panel configuration files.

A subpanel is “attached” to a control in the Main Panel.

Figure 15–3 A subpanel's container is the control to which it is attached

Graphic

The attachment is done in the subpanel definition. The CONTAINER_NAME field specifies the control to which the subpanel is attached:

CONTROL control_name
 {
    …
 }

 SUBPANEL subpanel_name
 {
 	CONTAINER_NAME 					control_name
 	…
 }

To Create a New System-Wide Subpanel

  1. Locate the control_name of the control in the Main Panel to which you want to attach the subpanel.

    If the control is one of the built-in controls, its definition is in /usr/dt/appconfig/types/language/dtwm.fp.

  2. Create a new file /etc/dt/appconfig/types/language/*.fp.

  3. Define the subpanel:

    	SUBPANEL subpanel_name
     	{
     		CONTAINER_NAME			control_name
     		TITLE						value
     		KEYWORD				value
     		…
     	}
  4. Save the new configuration file.

  5. Choose Restart Workspace Manager from the Workspace menu.

Customizing the Built-in Subpanels

You can modify general properties (such as the title) and the contents of the built-in subpanels.

To Modify General Properties of a Built-In Subpanel

  1. Create a new Front Panel configuration file:

    • System-wide: /etc/dt/appconfig/types/language/name.fp

    • Personal: HomeDirectory/.dt/types/name.fp.

  2. Copy the entire default SUBPANEL definition from /usr/dt/appconfig/types/language/dtwm.fp to the new file:

    	SUBPANEL   subpanel_name
     	{
      	 …
     	}
  3. Modify the subpanel definition.

  4. Save the new configuration file.

  5. Choose Restart Workspace Manager from the Workspace menu.

    For example, the following definition, placed in the file /users/janice/.dt/types/PerApps.fp, changes the name of the Personal Applications subpanel:

    SUBPANEL PersAppsSubpanel
     {
     	CONTAINER_NAME					TextEditor
     	TITLE								Janice's Applications
     }

To Add a System-Wide Control to a Built-In Subpanel

  1. Create a Front Panel configuration file /etc/dt/appconfig/types/language/name.fp.

  2. Define the system-wide control in the file.

    Use the CONTAINER_NAME and CONTAINER_TYPE fields to specify the container for the control:

    	CONTROL control_name
     	{
     		CONTAINER_NAME					subpanel_name
     		CONTAINER_TYPE					SUBPANEL
     		…
     	}

    See Defining Front Panel Controls.

  3. Save the configuration file.

  4. Choose Restart Workspace Manager from the Workspace menu.

    For example, the following control defined in a new file /etc/dt/appconfig/types/language/DigitalClock.fp adds the DigitalClock (in the Desktop_Tools application group) to the Personal Applications subpanel for all users.

    CONTROL DigitalClockControl
     {
     	TYPE						icon
     	CONTAINER_NAME			PersAppsSubpanel
     	CONTAINER_TYPE			SUBPANEL
     	ICON						Dtdgclk
     	PUSH_ACTION				DigitalClock
     	PUSH_RECALL				True
     }

To Remove a Control from a Built-In Subpanel

    Use the same procedure as for removing a Main Panel control. See To Remove a Control.

To Remove the Install Icon Control

    Add the following field to the subpanel definition:

	CONTROL_INSTALL					False

To Change the Auto-Close Behavior of Subpanels

The default behavior of subpanels is to close when the user chooses a control, unless the user has moved the subpanel from its original position.

The Front Panel can be configured to keep subpanels open until the user explicitly closes them.

  1. Create a new Front Panel configuration file in:

    • System-wide: /etc/dt/appconfig/types/language/*.fp

    • Personal: HomeDirectory/.dt/types/*.fp

  2. Copy the default PANEL definition from /usr/dt/appconfig/types/language/dtwm.fp to the new file:

    	PANEL FrontPanel
     	{
     	  …
     	}
  3. Add the following field to the PANEL definition:

    	SUBPANEL_UNPOST    False
  4. Save the new configuration file.

  5. Choose Restart Workspace Manager from the Workspace menu.

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:

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.

  1. 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.

  2. Create the icon image files for the control.

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

  3. Create a new Front Panel configuration file in:

    • System-wide: /etc/dt/appconfig/types/language/*.fp

    • Personal: HomeDirectory/.dt/types/*.fp

  4. Add the control definition to the file.

  5. Save the file.

  6. 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:

Creating a Control that Opens a File

Use these fields to define the control's behavior:

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:

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:

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.

  1. 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.

  2. Choose Restart Workspace Manager from the Workspace menu.

  3. 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:

  1. 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.

  2. 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:

Customizing the Workspace Switch

There are several ways to customize the workspace switch:

To Change the Default Number of Workspaces

    Modify the following Workspace Manager resource:

	Dtwm*workspaceCount:						n

For more information, see To Change the Number of Workspaces on a System-Wide Basis.

To Change the Number of Switch Rows

    Modify the NUMBER_OF_ROWS field in the SWITCH definition.

For example, the following definition defines a three-row switch.

SWITCH Switch
 {
 	CONTAINER_NAME				box_name
 	NUMBER_OF_ROWS				3
   …
 }

To Change or Add Controls in the Workspace Switch

  1. Create a Front Panel configuration file with the control definition.

    • Specify that the control be inside the switch:

      		CONTAINER_NAME   Switch
       		CONTAINER_TYPE   SWITCH
    • Specify the position in the switch:

      		POSITION_HINTS    n
      

      where n is an integer. The positions are numbered sequentially left-to-right, top-to-bottom. (For the default two-row switch, the positions are 1 through 4.)

  2. Create the icon for the control. The recommended size is 16 by 16 pixels.

    For example, the following control puts a Terminal control in the switch.

    		CONTROL SwitchTerminal  
    {    
    	TYPE                  icon    
    	CONTAINER_NAME        Switch    
    	CONTAINER_TYPE        SWITCH    
    	POSITION_HINTS        3    
    	ICON                  Fpterm    
    	LABEL                 Terminal    
    	PUSH_ACTION           Dtterm    
    	HELP_TOPIC            FPOnItemTerm    
    	HELP_VOLUME           FPanel  
    }

    The control uses a built-in icon and the same help topic used by the Terminal control in the Personal Applications subpanel.

General Front Panel Configuration

Front Panel's PANEL syntax allows you to:

General Steps

  1. Create a new Front Panel configuration file in /etc/dt/appconfig/types/language or HomeDirectory/.dt/types.

  2. Copy the default PANEL description from /usr/dt/appconfig/types/language/dtwm.fp to the new file.

  3. Edit the PANEL description.

    The new PANEL description has precedence over the default one.

To Change the Default Front Panel Location

    Use the PANEL_GEOMETRY field in the PANEL definition to specify the location.

For example, the following panel is in the upper right corner.

	PANEL SpecialFrontPanel
 	{
  	 PANEL_GEOMETRY      -1+1
  	  …
 	}

To Label Controls in the Main Panel

  1. Add the following line to the PANEL definition:

    	DISPLAY_CONTROL_LABELS   True
  2. Add a LABEL field to each control.

    The control_name is used if no LABEL is specified.

To Change the Click Behavior of Controls

    Use the CONTROL_BEHAVIOR field in the PANEL definition to specify how the user runs a control's PUSH_ACTION. Values for the field are:

    single_click—the user clicks the control to run the PUSH_ACTION

    double_click—the user double-clicks the control to run the PUSH_ACTION

To Create an Entirely New Front Panel

Creating a new Front Panel may be preferable when you want to make extensive changes.

To avoid conflict with the built-in Front Panel components, an entirely new Front Panel should use new names for the PANEL and other containers.

  1. Create the PANEL component for the new Front Panel. Give it a unique name:

    	PANEL front_panel_name
     	{
     	   …
     	}
  2. Create the new boxes and controls, using the new container names.

    If you want to use existing components, you must copy their definitions and change the CONTAINER_NAME value.

  3. Choose Restart Workspace Manager from the Workspace menu.

Example of Creating a Personal Front Panel with Three Rows

The following example changes the default Front Panel so that its controls are organized into three rows.

  1. Copy /usr/dt/appconfig/types/language/dtwm.fp to HomeDirectory/.dt/types/MyFrontPanel.fp. Give the file write permission.

    This is the file you will edit to provide the new Front Panel.

  2. Change the name of the Front Panel:

    	PANEL NewFrontPanel
  3. Change the name of the box named Top and edit its container name:

    	BOX NewFrontPanelTop
     	{
     	  CONTAINER_NAME					NewFrontPanel
     	  POSITION_HINTS					first
     	  … 	
    	}
  4. Add box definitions for the middle and bottom rows:

    	BOX NewFrontPanelMiddle
     	{
     	  CONTAINER_NAME						NewFrontPanel
      	 POSITION_HINTS						second
     	}
     
    	BOX NewFrontPanelBottom
     	{
     	  CONTAINER_NAME						NewFrontPanel
     	  POSITION_HINTS						second
     	}
  5. Change the CONTAINER_NAME of the following controls to NewFrontPanelTop:

    • Clock

    • Date

    • Home

    • TextEditor

    • Mail

  6. Change the CONTAINER_NAME of the following controls to NewFrontPanelBottom:

    • Printer

    • Style

    • Applications

    • Help

    • Trash

  7. Change the CONTAINER_NAME of the switch to NewFrontPanelMiddle.

  8. Choose Restart Workspace Manager from the Workspace menu.