DTFPFILE(4)

💅 NAME 💅

dtfpfile — format and locations of front panel configuration files

✨ SYNOPSIS ✨

set DtDbVersion=version_number
set VariableName=variable_value
RecordType record_name
{
        # Comment
        Keyword Value
        Keyword Value
        ...
}

🌸 DESCRIPTION 🌸

okay bestie, so the dtfpfile front panel database is basically the glow-up guide for the components that define what’s on the front panel and what it actually does. Files with front panel definitions have to end with the .fp suffix, periodt. Like the action and data type database, the front panel database gets built by reading every file ending in .fp that shows up in the search path specified by the DTDATABASESEARCHPATH environment variable. ✨

See dtdtfile(4) for the full scoop on the directory locations where these database files live, plus the specific syntax for the database files. 🫶

🎀 File Format 🎀

The general syntax of the front panel configuration files is exactly what’s up there in the SYNOPSIS section. No cap.

The Comments, Versions and Variables fields are described in dtdtfile(4).

The front panel record types each have a set of Keyword and Value pairs. There are six record types defined: PANEL, BOX, SUBPANEL, SWITCH, CONTROL and ANIMATION. Each record type has its own set of keywords, and many of the keywords are used for multiple record types. iykyk 💅

🦋 Record Types 🦋

🌟 PANEL front panel name 🌟

The PANEL record type defines the outermost container of the front panel. It can contain one or more BOXes and optionally repositioning handles, a menu and a minimize button. The keywords defined for PANEL are:

• CONTROL_BEHAVIOR — value: (double_click/ single_click); default: single_click
• DISPLAY_CONTROL_LABELS — value: (True/False); default: False
• DISPLAY_HANDLES — value: (True/False); default: True
• DISPLAY_MENU — value: (True/False); default: True
• DISPLAY_MINIMIZE — value: (True/False); default: True
• HELP_STRING — value: string; default: NULL
• HELP_TOPIC — value: topic name; default: NULL
• HELP_VOLUME — value: volume name; default: FPanel
• LOCKED — value: (True/False); default: False
• PANEL_GEOMETRY — value: {+-}xoffset[{+-}yoffset]; default: NULL
• RESOLUTION — value: (high/medium /low/match_display); default: match_display
• SUBPANEL_UNPOST — value: (True/False); default: True

Also literally in the PANEL table: tgroup dispwid="5.93in".

🧸 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 BOXes within a PANEL are stacked vertically. The keywords defined for BOX are:

• CONTAINER_NAME — value: front panel name; default: NULL (required)
• DELETE — value: (True/False); default: False
• HELP_STRING — value: string; default: NULL
• HELP_TOPIC — value: topic name; default: NULL
• HELP_VOLUME — value: volume name; default: FPanel
• LOCKED — value: (True/False); default: False
• POSITION_HINTS — value: (first/last/integer ≥ 1); default: first

🎀 SUBPANEL subpanel name 🎀

The SUBPANEL record type defines a secondary container for CONTROLs that 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:

• CONTAINER_NAME — value: control name; default: NULL (required)
• CONTROL_INSTALL — value: (True/False); default: True
• DELETE — value: (True/False); default: False
• HELP_STRING — value: string; default: NULL
• HELP_TOPIC — value: topic name; default: NULL
• HELP_VOLUME — value: volume name; default: FPanel
• LOCKED — value: (True/False); default: False
• TITLE — value: string; default: NULL

🔥 SWITCH switch name 🔥

The SWITCH record type defines a container within a BOX that 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:

• CONTAINER_NAME — value: box name; default: NULL (required)
• DELETE — value: (True/False); default: False
• HELP_STRING — value: string; default: NULL
• HELP_TOPIC — value: topic name; default: NULL
• HELP_VOLUME — value: volume name; default: FPanel
• LOCKED — value: (True/False); default: False
• NUMBER_OF_ROWS — value: integer; default: 2
• POSITION_HINTS — value: (first/last/integer ≥ 1); default: first

Also literally in the SWITCH table: tgroup dispwid="5.93in".

💜 CONTROL control name 💜

The CONTROL record type defines the main functional component of the front panel. CONTROLs typically have actions defined for them that are invoked on selection or drag and drop or both. CONTROLs are displayed with icons or labels or both and can have iconic animations associated with them. The keywords defined for CONTROL are:

• ALTERNATE_ICON — value: image name; default: NULL
• CLIENT_GEOMETRY — value: width x height; default: NULL
• CLIENT_NAME — value: client name; default: NULL
• CONTAINER_NAME — value: (box name/ switch name/subpanel name); default: NULL (required)
• CONTAINER_TYPE — value: (BOX/SWITCH/ SUBPANEL); default: NULL (required)
• DATE_FORMAT — value: format string; default: %b%n%e
• DELETE — value: (True/False); default: False
• DROP_ACTION — value: action_name; default: NULL
• DROP_ANIMATION — value: animation name; default: NULL
• FILE_NAME — value: pathname; default: NULL
• HELP_STRING — value: string; default: NULL
• HELP_TOPIC — value: topic name; default: NULL
• HELP_VOLUME — value: volume name; default: FPanel
• ICON — value: image name; default: NULL
• LABEL — value: string; default: NULL
• LOCKED — value: (True/False); default: False
• MONITOR_TYPE — value: (none/mail/ file); default: none
• POSITION_HINTS — value: (first/last/integer ≥ 1); default: first
• PUSH_ACTION — value: action_name; default: NULL
• PUSH_ANIMATION — value: animation name; default: NULL
• PUSH_RECALL — value: (True/False); default: False
• TYPE — value: (blank/busy/ client/clock/date/ file/icon); default: icon

🌈 ANIMATION animation name 🌈

The ANIMATION record types are a sequence of image name and time delay pairs that are displayed by a CONTROL on a PUSH_ACTION or DROP_ACTION.

• ANIMATION — value: image name [ millisecond delay]; default: None [200]

💖 Keyword and Value Descriptions 💖

okay so here’s the rundown of every keyword the front panel defines, bestie. 🫶

✨ ALTERNATE_ICON ✨

Used with 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 control with a mail or file value for the MONITOR_TYPE. 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 with 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 with record types of: CONTROL.

Used with control type 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 with record types of: CONTROL.

Used with control types of: client or icon.

Used with control keywords of: PUSH_RECALL.

• CLIENT_NAME — tells the panel which executable a control is tied to. You need it for controls with a record type of client (an X client chillin' inside the front panel) and for icon controls when the keyword PUSH_RECALL is True. The value is the name of the executable, or it can be set with a command-line argument for some clients (like xterm -name panelterm). Want the client name of a currently-running client? Just run xprop and grab it — the first string of the WM_CLASS property is exactly the value you want. 💅
• CONTAINER_NAME — used with record types of: BOX, SUBPANEL, SWITCH and CONTROL.

This one links a component to its parent. Like, the CONTAINER_NAME value of a SWITCH tells the front panel which BOX it should go inside. And since controls can live in several different component types, CONTAINER_NAME works together with CONTAINER_TYPE to pin down a control's parent. 🫶

• CONTAINER_TYPE — used with record types of: CONTROL.

This defines a control's parent type. It's how the panel identifies a control uniquely so it can be created inside the right parent.

• CONTROL_BEHAVIOR — used with record types of: PANEL.

The mechanism for setting the user model for front panel controls — aka you get to pick whether a control fires its PUSH_ACTION on a single click or a double click. ✨

• CONTROL_INSTALL — used with record types of: SUBPANEL.

Turns dynamic control installation into subpanels on or off. Set it to True and the control installation area shows up inside the subpanel.

• DATE_FORMAT — used with record types of: CONTROL, and with control types of: date.

Sets the layout of the date string for a control of type date. Same format as the UNIX strftime(3) function uses — iykyk.

• DELETE — used with record types of: BOX, SUBPANEL, SWITCH and CONTROL.

DELETE overrides and removes a non-locked component from the front panel. It's how you get rid of system default front panel components without replacing the default files. To use it, you stash a copy of the component definition — with the extra DELETE keyword added — in a file with an .fp suffix in the user's directory or the application type's directory. 🗑️

• DISPLAY_CONTROL_LABELS — used with record types of: PANEL.

Says whether the controls inside the front panel's boxes get their labels displayed.

• DISPLAY_HANDLES — used with record types of: PANEL.

Set DISPLAY_HANDLES to True and boom — the move handles show up along the left and right edges of the front panel.

• DISPLAY_MENU — used with record types of: PANEL.

Set DISPLAY_MENU to True and DISPLAY_HANDLES to True too, and the system menu button appears in the upper left hand corner of the front panel.

• DISPLAY_MINIMIZE — used with record types of: PANEL.

Set DISPLAY_MINIMIZE to True and DISPLAY_HANDLES to True too, and the minimize button appears in the upper right hand corner of the front panel. 🎀

• DROP_ACTION — used with record types of: CONTROL.

Specifies the function invoked when a drop happens on the control.

• DROP_ANIMATION — used with record types of: CONTROL, and with all control types except: client.

The name of an animation record to display when a drop happens on the control. Heads up bestie: the control has to have a DROP_ACTION defined for the animation to actually be used. 💀

• FILE_NAME — used with record types of: CONTROL, and with control types of: icon and file.

For a control of type file, FILE_NAME is the pathname of the file used for the control — the file's file type, actions and images get extracted from the action database for the control.

For MONITOR_TYPE mail and file, FILE_NAME specifies the pathname of the file the front panel monitors, either for mail arrival or for some other user-defined data.

For MONITOR_TYPE file, the ALTERNATE_ICON image gets displayed when the monitored file is non-empty, and the ICON image gets displayed if the file is empty or doesn't exist at all.

For MONITOR_TYPE mail, the ALTERNATE_ICON image gets displayed when the file increases in size. 📬

• HELP_STRING — used with record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL.

An on-line help string to display when help is requested over a front panel component. Since every component type can have its own help string, there's a precedence order for deciding which one to show: control help takes precedence over box help, switch help and subpanel help, and box help takes precedence over subpanel help. Also — importance check — the HELP_STRING value is only used if no HELP_TOPIC value is defined. 👑

• HELP_TOPIC — used with record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL.

An on-line help topic, used with either the default help volume or a help volume specified by the HELP_VOLUME keyword, to display help information when it's requested over a front panel component. Just like HELP_STRING, each component type can have a help topic associated with it and the same precedence rules apply.

• HELP_VOLUME — used with record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL.

When HELP_VOLUME is used together with HELP_TOPIC, it defines the help information displayed for a front panel component. 🦋

• ICON — used with record types of: CONTROL, and with control types of: icon, file and busy.

The image to display within a control.

• LABEL — used with record types of: CONTROL, and with control types of: icon, file, clock and busy.

The string to display when a control is in a subpanel.

• LOCKED — used with record types of: PANEL, BOX, SUBPANEL, SWITCH and CONTROL.

The mechanism that prevents a component definition of identical type, name and parent from overriding (replacing) this definition. Since the front panel can be defined across multiple configuration files, this gives you the flexibility to override components found earlier in the search path. Just like actions and file types, it lets the front panel be customized at several levels. 🔒

• MONITOR_TYPE — used with record types of: CONTROL, and with control types of: icon and file.

Specifies the method of checking the file being monitored, which is the file named by the keyword FILE_NAME.

• NUMBER_OF_ROWS — used with record types of: SWITCH.

Gives you control over the layout of the workspace switch buttons. Those buttons are arranged in a row-and-column layout, and NUMBER_OF_ROWS defines how many rows that layout has. The number of columns is derived from this value and the total number of switch buttons. ✨

• PANEL_GEOMETRY — used with record types of: PANEL.

A non-default location for positioning the front panel when it's created. By default, the front panel is centered along the bottom of the display.

• POSITION_HINTS — used with record types of: BOX, SWITCH and CONTROL.

Sets the ordering of boxes in the front panel, of the switch and controls in boxes, and of controls in subpanels. When two components have the same value for POSITION_HINTS, whichever one was read from the configuration file first gets placed first. 🥇

• PUSH_ACTION — used with record types of: CONTROL.

The function invoked when a selection occurs on the control.

• PUSH_ANIMATION — used with record types of: CONTROL, and with all control types except: client.

The name of an animation record to display when a selection occurs on the control. Again — the control must have a PUSH_ACTION defined for the animation to be used. No action, no animation, no cap. 🙈

• PUSH_RECALL — used with record types of: CONTROL, and with control keywords of: CLIENT_NAME.

When PUSH_RECALL is True, it means only one process can be started by the control. If that process is already running, it gets displayed within the current workspace and shuffled to the top of the window stack. The value of the CLIENT_NAME keyword is what identifies the process for this push recall behavior.

• RESOLUTION — used with record types of: PANEL.

Lets you force the icon set for the front panel to a particular set. By default, the front panel figures out the display resolution at runtime and goes with the high resolution icon set if the display width is 1024 pixels or wider. 🖥️

• SUBPANEL_UNPOST — used with record types of: PANEL.

Set SUBPANEL_UNPOST to True and a subpanel hides itself whenever a PUSH_ACTION occurs on one of the subpanel controls. But — plot twist — if the subpanel has been torn off of the front panel, its behavior is forced to remain posted on PUSH_ACTION.

• TITLE — used with record types of: SUBPANEL.

The string displayed in the title area of the subpanel.

• TYPE — used with record types of: CONTROL.

The front panel defines a whole bunch of different control types, bestie:

• blank — space-holder control
• busy — busy light
• client — a client window

• clock — front panel clock ⏰ literally just a lil clock chilling on your panel, telling you the time bestie.
• date — front panel date (the original page spells this one FroCaretnt panel date — yes, FroCaretnt, we're keeping it, it's giving typo era 💀 but the detail stays).
• file — references a file on the file system and uses that file's actions and image 🗂️ so instead of hardcoding everything, you point at a file and it borrows the whole fit — actions and image.
• icon — front panel general control 🌸 the general-purpose icon situation, the main character of panel items.

---

🎀 FILES 🎀

okay so when you don't tell it otherwise, this is the config file it reaches for by default — the icon of default configs, no cap:

/nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/appconfig/types/C/dtwm.fp

and when front panel components get created dynamically (yes, they spawn themselves, obsessed), the attributes for those live in this directory:

$HOME/.dt/types/fp_dynamic

like, that's their whole little home. 🏠

---

💅 APPLICATION USAGE 💅

so if loading any of those front panel database files goes sideways 😭 the errors don't just vanish into the void — they get written to your $HOME/.dt/errorlog file. so when something's acting up, that's your first stop, bestie. read the log. the log knows everything. 🫶

---

🌈 SEE ALSO 🌈

go touch grass in these other pages, they're all linked up:

• dtwm(1)
• strftime(3)
• dtdtfile(4)

---

and that's the whole page!! 🎉 you've officially read all of dtfpfile(special file) — check the footer for the date if you need the receipts, but honestly you ate this. go build a gorgeous front panel, you deserve it. 💖✨🎀🦋