dtfpfile(4) — File Formats
NAME
dtfpfile — format and locations for front panel configuration files.
SYNOPSIS
RecordType record_name
{
# Comment
Keyword Value
Keyword Value
.
.
.
}
DESCRIPTION
The front panel database provides definitions for the components which define the content and functionality of the front panel. Files containing front panel definitions must end with the .fp suffix. Like the Action/Data Type database, the front panel database is constructed by reading all files, ending in the .fp suffix, found in the search path specified by the DTDATABASESEARCHPATH environment variable.
See dtdtfile(4) for a complete description of the directory locations where these database files are found and for a description of the specific syntax for the database files.
FILE FORMAT
The general syntax of the Front Panel configuration files is as described above in the SYNOPSIS section of this man page. Descriptions of Comments, Versions and Variables can be found in dtdtfile(4).
The front panel defines a new set of Record Types each with a set of Keyword, Value pairs. There are a total of six record types defined (PANEL, BOX, SUBPANEL, SWITCH, CONTROL and ANIMATION). Each record type has a set of keywords defined for it. Many of the keywords are used for multiple record types. In the following tables containing the listing of the keywords for each record type, a ∗ in the Default column of the table indicates that this value must be specified.
Record Types
PANEL "front panel name"
The PANEL record type defines the outermost container of the front panel. It can contain one or more BOX’es and optionally repositioning handles, a menu and minimize button. The keywords defined for PANEL are as follows.
| PANEL Record Type Keyword Set | |||
| Keyword | Value | Default | |
| PANEL_GEOMETRY | [+/- x-offset][+/- y-offset] | Null | |
| DISPLAY_HANDLES | (True/False) | True | |
| DISPLAY_MENU | (True/False) | True | |
| DISPLAY_MINIMIZE | (True/False) | True | |
| RESOLUTION | (high/medium/low/match_display) | match_display | |
| CONTROL_BEHAVIOR | (double_click/single_click) | double_click | |
| DISPLAY_CONTROL_LABELS | (True/False) | False | |
| SUBPANEL_UNPOST | (True/False) | True | |
| LOCKED | (True/False) | False | |
| HELP_STRING | string | Null | |
| HELP_TOPIC | topic name | Null | |
| HELP_VOLUME | volume name | FPanel | |
BOX "box name"
The BOX record type defines a container within a PANEL that can hold a row of CONTROLS and at most one SWITCH container. Multiple BOX’es within a PANEL are stacked vertically. The keywords defined for BOX are as follows.
| BOX Record Type Keyword Set | |||
| Keyword | Value | Default | |
| CONTAINER_NAME | front panel name | Null ∗ | |
| POSITION_HINTS | (first/last/1-99) | first | |
| LOCKED | (True/False) | False | |
| DELETE | (True/False) | False | |
| HELP_STRING | string | Null | |
| HELP_TOPIC | topic name | Null | |
| HELP_VOLUME | volume name | FPanel | |
The SUBPANEL record type defines a secondary container for CONTROLs which "slide up" from the front panel. SUBPANELs can also contain a drop zone where new controls can be dynamically added. The keywords defined for SUBPANEL are as follows.
| SUBPANEL Record Type Keyword Set | |||
| Keyword | Value | Default | |
| CONTAINER_NAME | control name | Null ∗ | |
| CONTROL_INSTALL | (True/False) | True | |
| TITLE | string | Null | |
| LOCKED | (True/False) | False | |
| DELETE | (True/False) | False | |
| HELP_STRING | string | Null | |
| HELP_TOPIC | topic name | Null | |
| HELP_VOLUME | volume name | FPanel | |
The SWITCH record type defines a container within a BOX which contains a set of push buttons each of which give access to a corresponding workspace. See dtwm(1) for a description of the multiple workspace capabilities. Also contained within the SWITCH container is an optional set of CONTROLs. These are presented in a column on each side of the push buttons. The keywords defined for SWITCH are as follows.
| SWITCH Record Type Keyword Set | |||
| Keyword | Value | Default | |
| CONTAINER_NAME | box name | Null ∗ | |
| POSITION_HINTS | (first/last/1-99) | first | |
| NUMBER_OF_ROWS | (1-N) | 2 | |
| LOCKED | (True/False) | False | |
| DELETE | (True/False) | False | |
| HELP_STRING | string | Null | |
| HELP_TOPIC | topic name | Null | |
| HELP_VOLUME | volume name | FPanel | |
CONTROL "control name"
The CONTROL record type defines the main functional component of the front panel. CONTROL’s typically have actions defined for them that are invoked on selection and/or drag & drop. CONTROL’s are displayed with icons or labels and can have iconic animations associated with them. The keywords defined for CONTROL are as follows.
| CONTROL Record Type Keyword Set | |||
| Keyword | Value | Default | |
| TYPE | (blank/busy/icon/client/clock/date/file) | Null ∗ | |
| CONTAINER_TYPE | (BOX/SWITCH/SUBPANEL) | Null ∗ | |
| CONTAINER_NAME | (box name/switch name/subpanel name) | Null ∗ | |
| POSITION_HINTS | (first/last/1-99) | first | |
| ICON | image name | Null | |
| ALTERNATE_ICON | image name | Null | |
| LABEL | string | Null | |
| PUSH_ACTION | action_name | Null | |
| PUSH_ANIMATION | animation name | Null | |
| DROP_ACTION | action_name | Null | |
| DROP_ANIMATION | animation name | Null | |
| PUSH_RECALL | (True/False) | False | |
| MONITOR_TYPE | (none/mail/file) | none | |
| CLIENT_NAME | client name | Null | |
| CLIENT_GEOMETRY | [width x height] | Null | |
| FILE_NAME | file name | Null | |
| DATE_FORMAT | format string | %b%n%e | |
| LOCKED | (True/False) | False | |
| DELETE | (True/False) | False | |
| HELP_STRING | string | Null | |
| HELP_TOPIC | topic name | Null | |
| HELP_VOLUME | volume name | FPanel | |
ANIMATION "animation name"
ANIMATIONs are a sequence of image name/time delay pairs that are displayed by a CONTROL upon a PUSH_ACTION and/or DROP_ACTION.
| ANIMATION Record Type Keyword Set | |||
| Keyword | Value | Default | |
| ANIMATION | image name, [millisecond delay] | None, 200 | |
Keyword and Value Descriptions
The following list contains a description of each of the keywords defined by the front panel. ALTERNATE_ICON
• Used for record types of: CONTROL
• Used with control types of: busy and icon
ALTERNATE_ICON defines an image to be used to replace the normal image within a mail or monitor_file control in the front panel. The image is displayed when the file being monitored changes. For the busy control, ALTERNATE_ICON is cycled with ICON to give the blinking effect.
ANIMATION
• Used for record types of: ANIMATION
• Used with control keywords of: PUSH_ANIMATION and DROP_ANIMATION
ANIMATION defines a sequence of images to be displayed for either a PUSH_ACTION or DROP_ACTION. Each animation within the list is displayed in order with a default time separation of 200 milliseconds. For a slower or faster sequence, the image name value can be followed by the amount of time to display the image. If no time value is specified the previously specified value is used.
CLIENT_GEOMETRY
• Used for record types of: CONTROL
• Used with control types of: client
• Used with control keywords of: CLIENT_NAME
CLIENT_GEOMETRY specifies the size (in pixels) needed for the window of a client displayed within the front panel.
CLIENT_NAME
• Used for record types of: CONTROL
• Used with control types of: client or icon
• Used with control keywords of: PUSH_RECALL
CLIENT_NAME specifies a name used to associate a control with an executable. It is necessary for control types of client (an X client running within the front panel) and for icon when the keyword PUSH_RECALL is True. The value client name is the name of the executable or can be set via a command line parameter for some clients (xterm -name panelterm). The client name for a running client can be found by executing xprop. The first string of the WM_CLASS property is the value used.
CONTAINER_NAME
• Used for record types of: BOX, SUBPANEL, SWITCH, CONTROL
CONTAINER_NAME associates a component with it parent. For example, the CONTAINER_NAME value for a SWITCH tells the front panel which BOX to place it into. Since controls can reside several different component types, CONTAINER_NAME is used in conjunction with CONTAINER_TYPE to define a controls parent.
CONTAINER_TYPE
• Used for record types of: CONTROL
CONTAINER_TYPE defines a controls parent type. This is used to uniquely identify a control so that it can be created within the proper parent.
CONTROL_BEHAVIOR
• Used for record types of: PANEL
CONTROL_BEHAVIOR provides the mechanism for setting the user model for front panel controls. Controls can be set to invoke their PUSH_ACTION by either single click or double click.
CONTROL_INSTALL
• Used for record types of: SUBPANEL
CONTROL_INSTALL enables or disables dynamic control installation into subpanels. A value of True causes the control installation area to be displayed within the subpanel.
T
• Used for record types of: CONTROL
• Allowed for control types of: date
DATE_FORMAT specifies the layout of the date string for a control of type date. This format is used by the unix command strftime. See strftime(3) for a description of the format.
TE
• Used for record types of: BOX, SUBPANEL, SWITCH, CONTROL
DELETE is used to override and remove and non-locked component from the front panel. This is necessary to eliminate system default front panel components without replacing the default files. To use DELETE a copy of the component definition with the additioinal DELETE keyword is stored in a .fp file in the users or application types directory.
• Used for record types of: PANEL
DISPLAY_CONTROL_LABELS specifies whether the controls contained within the front panels boxes will have their labels displayed.
• Used for record types of: PANEL
DISPLAY_HANDLES, if set to True causes the move handles to be displayed along the left and right edges of the front panel.
• Used for record types of: PANEL
DISPLAY_MENU, if set to True with DISPLAY_HANDLES also set to True causes the system menu button to be displayed in the upper left hand corner of the front panel.
NIMIZE
• Used for record types of: PANEL
DISPLAY_MINIMIZE, if set to True with DISPLAY_HANDLES also set to True causes the minimize button to be displayed in the upper right hand corner of the front panel.
• Used for record types of: CONTROL
DROP_ACTION specifies the function that is invoked when a drop occurs on the control.
• Used for record types of: CONTROL
• Allowed for all control types except: client
DROP_ANIMATION specifies the name of an animation record to be displayed when a drop occurs on the control. The control must have a DROP_ACTION defined for the animation to be used.
FILE_NAME
• Used for record types of: CONTROL
• Allowed for control types of: icon and file
For the control type of file, FILE_NAME is the name of the file to be used for the control. The files file type, actions and images are extracted from the action database for the control. For control types of main and monitor_file, FILE_NAME specifies the name of the file the front panel is to monitor for either mail arrival or some other user defined data. For control types of monitor_file, the ALTERNATE_ICON image is displayed when the monitored file is non-empty. The ICON image is displayed if the file is empty or non-existent. For controls types mail, the ALTERNATE_ICON image is displayed when the file increases in size.
• Used for record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL
HELP_STRING specifies an on-line help string to display when help is requested over a front panel component. Since each component type can have a help string associated with it, there is a precedence used in deciding which help string to display. Control help takes precedence over box help, switch help and subpanel help. Box help takes precedence over panel help.
The HELP_STRING value is used only if no HELP_TOPIC value has been defined.
• Used for record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL
HELP_TOPIC specifies an on-line help topic which is used with either the default help volume or a help volume specified by the HELP_VOLUME keyword to display help information when requested over a front panel component. Like the HELP_STRING keyword, each component type can have a help topic associated with it and the same precedence rules are used.
• Used for record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL
HELP_VOLUME, when used in conjunction with HELP_TOPIC, defines the help information to be displayed for a front panel component.
ICON
• Used for record types of: CONTROL
• Allowed for controls types of: icon, file, and busy.
ICON specifies image to be displayed within a control.
LABEL
• Used for record types of: CONTROL
• Allowed for control types of: icon, file, clock and busy.
LABEL specifies the string to be displayed when a control is in a subpanel.
LOCKED
• Used for record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL
LOCKED provides the mechanism to prevent a component definition of identical type, name and parent from overriding (replacing) this definition. Since the front panel can be defined within multiple configuration files, it provides the flexibility override components found earlier in the search path. Like Actions and Filetypes, this gives the ability to customize the front panel at several levels.
MONITOR_TYPE
• Used for record types of: CONTROL
• Allowed for control types of: icon and file
MONITOR_TYPE specifies the method of checking the file being monitored, specified by the keyword MONITOR_FILE.
NUMBER_OF_ROWS
• Used for record types of: SWITCH
NUMBER_OF_ROWS provides control over the layout of the workspace switch buttons.
PANEL_GEOMETRY
• Used for record types of: PANEL
PANEL_GEOMETRY specifies a non-default location to position the front panel when it is created. By default, the front panel is centered along the bottom of the display.
POSITION_HINTS
• Used for record types of: BOX, SWITCH, and CONTROL
POSITION_HINTS specifies the ordering of boxes in the front panel, the switch and controls in boxes and controls in subpanels. When two components have the same value for POSITION_HINTS, the first one read from the configuration file is placed first.
PUSH_ACTION
• Used for record types of: CONTROL
PUSH_ACTION specifies the function that is invoked when a selection occurs on the control.
PUSH_ANIMATION
• Used for record types of: CONTROL
• Allowed for all control types except: client
PUSH_ANIMATION specifies the name of an animation record to be displayed when a selection occurs on the control. The control must have a PUSH_ACTION defined for the animation to be used.
PUSH_RECALL
• Used for record types of: CONTROL
• Used with control keywords of: CLIENT_NAME
PUSH_RECALL, when True specifies that only one process can be started by the control. If the process is already running, it is displayed within the current workspace and shuffled to the top of the window stack. The value for the CLIENT_NAME keyword is used to identify the process for push recall behavior.
RESOLUTION
• Used for record types of: PANEL
RESOLUTION, allows the icon set for the front panel to be forced to a particular set. By default, the front panel will determine the display resolution at runtime and choose the high resolution icon set if the display width is 1024 pixels or wider.
NPOST
• Used for record types of: PANEL
SUBPANEL_UNPOST, when True, causes a subpanel to hide itself whenever a PUSH_ACTION occurs on one of the subpanels controls. If the subpanel has been "torn off" of the front panel, the behavior of the subpanel is forced to remain posted upon PUSH_ACTIONs.
TITLE
• Used for record types of: SUBPANEL
TITLE, specifies the string to be displayed in the title area of the subpanel.
TYPE
• Used for record types of: CONTROL
A number of different control types are defined by the front panel.
blank - Space-holder control.
busy - Busy light.
client - A client window.
clock - Front panel clock.
date - Front panel date.
file - References a file on the file system. Uses the files actions and image.
icon - Front panel general control.
FILES
The default Front Panel configuration file can be found in /usr/dt/appconfig/types/C/dtwm.fp. Files containing the attributes of dynamically created Front Panel components can be found in the directory $HOME/.dt/types/fp_dynamic.
ERRORS
Errors encountered when loading Front Panel database files are written to the CDE errorlog file. Records containing errors are rejected.