Panel configuration files

The layout and general appearance of the screen can be modified by editing "panel description files". These files store names, positions, and characteristics of labels, control buttons, text areas, and other user interface items. You may want to make adjustments to the layout because of different length names or different sized fonts at your installation, or perhaps set a tighter spacing to leave more screen space for other windows. You may prefer a different logical layout of the buttons, for example putting the "help" button in the upper left corner and "quit" button in the lower right. You can also change the names on labeled fields or buttons.

Visual features such as colors, frame border widths, fonts, as well as behavior of the mouse cursor, window stacking, etc. are controlled by windows.

First a few definitions. A "frame" is the outer container for related user interface components for the application program. It corresponds to a window on your screen and is therefore movable & resizable using the screen window manager. The dynamic positioning of the items inside a frame is limited, so that resizing a frame does not always provide a useful shape.

A frame is usually divided into subframes for different functions. One of these is the "list frame", also known as a choice list. It displays rows of text that the user can select with the mouse or keyboard. Some only allow a single item to be selected at a time while others support multi-selection, allowing any number of items to be selected. They are usually formatted to allow long names or verbal descriptions of the choices. If the number of items does not fit in the space provided, a scrollbar displays.

A "text frame" is a general writing area that the user can scroll vertically and horizontally, if needed. Some text frames can be typed into, for example to edit comments. Others are only for displaying information.

A panel is an area that holds control buttons, toggle switches, and short single line typing areas; a sort of cross between an instrument panel and a paper fill-in form. They are usually used to determine settings that are needed during an operation, or to start and stop operations in the same manner as from menus. Panels can be dynamic; certain settings will automatically disable some of the other settings if they are logically incompatible.

The main frame is considered to be the "parent" of the subframes contained in it – the "parent" of a button is the panel that contains it. Items are positioned using coordinates relative to their parent.

Below is an example frame and panel definition file for the tag configuration in the datamatic tools program. If you have the tagtool running on your screen then you can see the association between the description files and the result.

File "tagcnftool.f":

id 0 TagCnfTool;

tit Tag Configuration Tool;;

id 1 main tagcnftool.p;cls 70;;

id 2 names; scb 1;cal 1;x 0;blw main;rws 6;cls 30;cho ;;

id 2 choice; scb 1;cal 1;rgt names;blw main;rws 6;cls 40;cho ;;

The first row "id 0" gives the name of the frame. This name is used internally by application programs, so that unique names should be assigned to all the frames. The title field is written into the title bar of the window that contains this frame.

The next rows divide up the frame into subframes. The row "id 1" defines a control panel subframe named "main" that is 70 columns wide; the description of the panel is found in a separate file named "tagcnftool.p". The application program searches for this control panel with this name "main" so you should not change it.

Two choice panels (id 2) are located below the control panel, positioned by the request "blw main". Similarly the second choice panel is to the right of the first via the command "rgt names". The sizes of these choice panels are 6 character rows and 30 or 40 character columns. A list longer than the frame can be handled because the "scb 1" commands request scrollbars to be placed. The names of the choices will be provided by the program but an empty dummy initial choice ("cho ;") is provided in case the program doesn't find any tag types.

The expression "cal 1" means to enable "callbacks". This indicates that the frame will probably change during use since the application program will be called to examine your choice at the instant that you select it. Another use for callbacks is to check for errors in your input or in the data. Not all panel items need callbacks, since the application program might wait to examine the state of the panel only when you are finished using it. For these reasons you should not remove any callbacks in a panel definition, and there is no reason to add any if the application is not interested in the item.

The contents of the control panel are described by this panel file (simplified):

id 1 panel;;

id 1 OK;bim Done;col  0;row 0;w 8;bva 'd';lay 0;;

id 1 H;bim  Help;col 20;row 0;w 8;bva 'h';lay 0;;

id 1 BM;bim Modify Tag;col 14;row 1;w 11;bva 'M';lay 0;;

id 2 descr;lbl Description:;col 1;row 4;len  50;;

id 3 type; lbl Data Type:;col 1;row 5;cst 1;cal 1;

cho String;cho Numeric; cho Coded;;

id 2 min;lbl Min Value:;col 1;row 6;len 10;sho 0;;

id 2 max;lbl Max Value:;col 1;row 7;len 10;sho 0;;

The first line is special in that it actually uses the syntax reserved for frame files. In this case it gives a name but provides no other information since that was provided in the frame file.

The panel has 3 buttons labeled as shown by the "bim" (button image) command. The positions are set by the "row" and "col" fields and the width by the "w" field. The "lay" field selects layout 0, which means center all the buttons on the same row. The most important fields to the program are the names at the beginning of the line and the value sent to the program when the button is pressed, the "bva" button value field. These must not be changed or the program will not know what button was pressed.

A one-of-many selection is described by the "id 3" row, and the whole set of choices has a label "Data Type". The callback is set, since it affects other items on the panel (see next paragraph). In this case the choices are fixed and known in advance. You may change the spelling of the choices but the meaning is recognized by their order; that is, the program will respond to the uppermost choice to mean "String tag" regardless of the word printed on it. The "cst" tag selects a representation style in which the entries are stacked vertically.

The last two items are "fill-in" fields, single line text editors. They allow up to ten characters to be typed ("len 10"). The "sho 0" field causes the fill-ins to be initially invisible, since they are only used when the tag type is "String". The callback to the data type choice field turns the fill-ins on or off as needed.

Frame configuration files

A frame configuration file consists of records and comments. Each record consists of a variable number of data fields. For readability records are conventionally started on a new line, but the real record divider is a double semicolon (an empty field). C-style comments are supported: everything between "/*" and "*/" marks is ignored.

A data field is a name and a value and a terminating semicolon. The name is usually a short abbreviated word and must be terminated from the rest of the field by at least one space. The value part of the field may be multi-word; everything is scanned up to the semicolon. This means that normally semicolons may not be used within the name-value definition, since it terminates the definition (but see the paragraph below on quoting).

The first field of each record must have the name "id", and as a value a number indicating the object type and a name for the object. The types of subframes are:

The name may later be used by the application to find the object. For panels the id field gives the name of a panel definition file. The name may also simply be a dash '-', which means that the panel definitions follow immediately within the frame definition file itself. This kind of internal panel definition needs an empty record to terminate the definition of panel items and return to frame definitions. If a separate panel definition file is used then that file is expected to be in the same directory as the frame definition file.

The first record defines arguments for the top-level frame. The rest of the records represent subframes and specify their arguments.

Arguments for all subframe types

The following table describes frame arguments that apply to all subframes:

If the width (wdt or cls) or height (hgt or rws) dimension is set to zero then the frame extends to the respective edge of the top-level frame. If either of these dimensions is negative then it is taken as a percentage of the top-level frame's respective dimension.

Arguments for panels

The following arguments are available for panels:

Menus are loaded from the same directory as the frame or panel or ../menu if that exists. The use of the separate menu directory is preferred. See Menu configuration files.

Arguments for selection and multi-selection lists

The following arguments are available for selections and multiselects:

Icon files for choice images are found in the directory "*icon" parallel (same parent) to the panel directory.

RGB color can also be specified using a hexadecimal value in the form: 0xBBGGRR, where RR (red), GG (green) and BB (blue) are hexadecimal values between 00 and FF (same as decimal 0-255).

n = 24bit RGB value if n >= 0

n = -(palette index + 1) if n < 0)

Arguments for text windows

The following arguments are available for text windows:

Arguments for canvas windows

The following arguments are available for canvas windows:

Arguments for tree windows

The following arguments are available for tree windows:

Panel definition files

A panel definition file is built of records with the same general syntax as for frames, but with different argument names. The first record is the title record of the panel. If panel already exists then this data is ignored. Otherwise it is used to create the panel into the new frame.

The remaining records define panel items for the panel.

Panel items

The following item types are available for panels:

Panel item attributes

Attributes can be given to an item using the following data fields:

Button configuration

Widgets used to implement various input functions can be configured using standard resource files. Widgets implementing text, message or button items in the dialog window can be further configured using special configuration files. These files can be pointed to by the environment variables specified in the following table.

Button items

Buttons are numbered as follows:

A button can be configured if it has an entry in this config file. Otherwise defaults are used. The following items are needed for one entry:

<button_id> <label string> <width>

Dialog buttons

For each button the following entry is needed:

<button id> <x> <y>

Text items

Text items are numbered as follows:

Entries contain the following data:

<text id> <x> <y> <label string> <display length>

Example

The button label "Yes" in a yes/no widget should be changed to "Si".

First WM_BUTTON_ITEMS is set:

setenv WM_BUTTON_ITEMS /usr/mysettings/wm_button_items

In the file wm_button_items:

4'Si'6

This will produce a yes/no panel with "Si" replacing "Yes".