Panel Manager

Quick contents

Overview of the panel manager

Panel manager is a vlab system program used to control parameters during experiments. It displays and makes it possible to manipulate a user-defined control panel, and communicates with an application such as a simulation program, by sending messages editing its data file. (see Figure 1)

Figure 1 - Communication flow involving the panel manager

The panel manager runs as a completely separate process from the application. It inputs the panel definition from a file, and uses this information to open a window for the panel, create a pop-up menu, and display sliders and buttons specified by the user. An example window and corresponding definition file are shown in Figures 2 and 3.

Figure 2 - Example of a control panel

The following shows an example of a panel definition file:
 

panel name: Animate
background: 0
size: 170 400

type: SLIDER
name: Last frame
colors: 7 1
origin: 20 330
min/max: 0 100
value: 34
message: n 6 1 0 %d

type: SLIDER
name: First frame
colors: 7 1
origin: 20 265
min/max: 0 40
value: 0
message: n 5 1 0 %d

type: SLIDER
name: Swap interval
colors: 7 1
origin: 20 200
min/max: 0 20
value: 10
message: n 4 1 0 %d

type: BUTTON
name: dbl buffer
colors: 7 4
origin: 40 130
value: 1
message: o 1 %d

type: BUTTON
name: clear
colors: 7 4
origin: 40 80
value: 1
message: o 2 %d

type: BUTTON
name: scale
colors: 7 4
origin: 40 30
value: 0
message: o 3 %d

Figure 3 - Example of a control panel definition file

Controls may all appear in a single window or may be divided into several pages. Bistable buttons may be grouped so that only one button in the group will be on at any given time. Menus are used for panel control and may also contain optional user-defined items. A message format is specified for each control, and may refer to the current value returned by the control. When a control is modified, the manager will update and display its value, and send its associated message to the standard output device (stdout). Controls are manipulated by the left mouse button. 

Panel definition file format

The panel definition file contains all the information necessary to create, display and manipulate the control panel. It first describes the window to be used, and then provides a description of each control (slider, button or menu item). Blank lines may be used to separate each control's specifications, but the details of a single control MUST be on consecutive lines. Normally panel files have the name "panel.l"

The panel definition file may contain the following specifications:

The panel window definition

The first three lines of the file describe the panel window, and are formatted as follows:

        panel name: XXXXX
        colourmap: abcdef.map (optional)
        background: 999
        size: 999 999
panel name: the name of the window;
colourmap: the name of the color map file to load. This overrides any colourmaps specified on the command line;
background: the color index for the background;
size: the x and y dimensions of the window in pixels.

Page definition

A panel may be divided into several pages, each containing any number of controls. Pages are selected from the menu, and a new selection will overwrite the page previously displayed in the panel window. The format of a page definition is:

        type: PAGE
        name: XXXXX
        color: 999
        origin: 999 999
        message: XXXXX
name: the label that will appear in the window and on the menu;
color: the color index for the label;
origin: the x and y coordinates of the lower left corner of the label in pixels, measured from the lower left corner of the panel;
message: the string to be sent to stdout when a new page is selected.

Specification for all controls (sliders or buttons) for a page should follow this definition. The specifications for the current page end when a new page definition is encountered. If page definitions are used in the panel definition file, controls specified before the first page are ignored. When the panel is invoked, the first page will be displayed.

Slider definition

The format of a slider definition is:

        type: SLIDER
        name: XXXXX
        colors: 999 999
        origin: 999 999
        min/max: 999 999
        value: 999
        message: XXXXX
name: the label for the slider;
colors: the color index of the slider outline and label, the color index of the filled area of the slider;
origin: the x and y coordinates of the slider in the window, measured in pixels from the lower left corner of the window, to the bottom left corner of the slider area (see below);
min/max: minimum and maximum values for the slider;
value: the default slider value;
message: the string sent to stdout . The message may contain a %d field to output the current value of the control, and will be terminated by the newline character.

The dimensions of the slider are 12x128 pixels, but space must also be allocated for its label (below the slider) and the display of its current value (above). Assuming the label is no longer than the slider's length, the total area for a slider is 52x128 pixels. The origin specified for the slider is the bottom left corner of this area. The bottom of the slider itself is 20 pixels above this corner.

Button definition

The format of a button definition is:

        type: BUTTON
        name: XXXXX
        colors: 999 999
        origin: 999 999
        value: 999
        message: XXXXX
name: the label for the button;
colors: the color index of the button's outline and label, the color index of the fill color;
origin: the x and y coordinates of the button in the window, in pixels, measured from the bottom left corner of the window, to the bottom left corner of the button;
value: the default value (0 = off, 1 = on, -1 = monostable);
message: the string sent to stdout . The message may contain a %d field to output the current value of the control, and will be terminated by the newline character.

The dimensions of the button are 24x100 pixels. The label appears inside the button, which limits it to approximately 10 characters. When the button is on, it is filled with the fill color, otherwise it is filled with the background color. Monostable buttons will turn momentarily on, and then turn off. They are defined by specifying a default value of -1, and will always return this value in the %d field.

Group definition

The format of a group definition is:

        type: GROUP
        color: 999 
        XXXXX
        XXXXX
        ...
        ENDGROUP
color: the index of the outline color used to delineate the group;
XXXXX: the names of previously defined bistable buttons.

The group is delineated by a rectangle from the lower left button to the upper right button. When a button in a group is selected, it is turned on and its associated message is output. All other buttons in the group are turned off, but no messages are sent by them. Thus one button in the group is ALWAYS on. If the button that is currently on is pressed again, it will remain on, and its message will be sent again. If paging is used, the group definition must be part of the specifications for the page on which the buttons appear.

Label definition

The format of a label definition is:

        type: LABEL
        name: XXXXX
        color: 999
        origin: 999 999
name: the string to be printed;
color: the color index for the string;
origin: the x and y coordinates of the lower left corner of the string field, measured in pixels from the lower left corner of the window.

A label defined within a page definition will appear only on that page. There are no globally defined labels.

Menus

Default items

Each panel will have a menu associated with it. The menu will appear as a pop-up menu, and is controlled by the right-mouse button. Each menu contains five permanent items handled by the panel manager.

Page control

If paging is used, then the menu will contain an item displaying the name of each page. When a page item is selected, the corresponding panel page will be displayed. These page items will appear above the permanent default menu items, but below the Select item.

Other items

User-defined menu items may also be specified, and will appear above the last 4 default menu items.

The format of a user-defined menu item is:

        type: MENU
        name: XXXXX
        message: XXXXX
name: the label that will appear on the menu;
message: the string to be sent to stdout when that item is selected from the menu.

When paging is used, the user-defined menu items should be typically specified before the first page definition or after the last one, depending on whether the items should appear before or after the page names on the menu.

Extensions

Within vlab panel files are named "panel.l" and the colourmap index either references a provided colourmap or the system palette. To improve compatibility with L-studio the panel program has been expanded and is now capable of loading the L-studio format panel files.

When comparing L-studio panel files to vlab panel files there are a number of key differences as outlined below:

The panel manager is able to load the L-studio panel files without issue, and if the panel is changed when you exit panel manager you will be prompted to save the changes to the file. When saving you can select which format you would like the panel file saved in. This is useful for converting L-studio panels into the vlab format if desired.

NOTE: If you have changed the colours of any objects on the panel, it is important that you create a colourmap file when saving your changes, or save the file back into the ".pnl" format. This will prevent any colours from being lost.

The color map and save format can be selected through the save dialog. At the top you can select whether to save in the Windows or Mac/Linux format, then there are check boxes to select whether or not to save the panel file and/or the color map.

Interfacing with an application

Simulation programs in the virtual laboratory are assumed to obtain their initial parameter values from data files. The panel manager can be interfaced to any such program that has the ability to reread its data files. The communication flow in such an interface is shown in Figure 1.

The parameter editor interprets messages from the panel manager and edits the corresponding parameter in the appropriate data file. The modified data file may subsequently be read again by the application program. Thus the steps involved in modification of the parameters are:

The advantage of using a parameter editor is that it is the only component that needs to be tailored when connecting panels to arbitrary applications.

Parameter editors

Two parameter editors are commonly used in the vlab system. 

Awkped

Parameter file editor using awk.

Usage:

awkped file_name [-lstudio]

Description:

Processes stdin input messages to edit the file specified on the command line using awk. The result then replaces the original file.

awkped interprets messages of four types of formats from stdin with an optional flag to modify the matching behavior.

The "-lstudio" flag causes awkped to count the field number starting from the colon ":" symbol in the given line instead of starting the count at the beginning of the line.

The argument formats are as follows:

        line field value scale
        d string value scale
        n line field scale10 value
        o line [on|off]
line: the line number to be edited,
field: the field number of a numeric value,
scale: an actual scaling factor (value will be divided by this factor),
scale10: a power of 10 scaling factor (value will be multiplied by this factor),
value: an integer or floating point number,
string: the name of the field - as used in a #define statement in a data file.

Normally this input is piped to awkped from the panel manager.

Awkped uses this input to edit a parameter file containing lines of the format:

        parameter-name: value1 [, value2 [, value3 ]]
        #define string value1
        parameter-name: value1 [, value2 [, value3 ]]
        parameter-name: [on|off]

where value1, value2, value3 are integer or floating point numbers.

Examples:

If awkped reads the message:

        1 3 459 100

and the first line of the parameter file is:

        light direction: 10, 20, 30

then after the edit, if the "-lstudio" flag was specified the resulting line will become:

        light direction: 10, 20, 4.59

or if it was not:

        light direction: 4.59, 20, 30


If awkped reads the message:

        d direction 32  0.1

and the parameter file contains the line:

        #define  direction  23.0

then after the edit, the resulting parameter file will contain:

        #define  direction  320.0


If awkped reads the message:

        n 1 3 -2 459

and the first line of the parameter file is:

        light direction: 10, 20, 30

then after the edit, if the "-lstudio" flag was specified the resulting line will become:

        light direction: 10, 20, 4.59

or if it was not:

        light direction: 4.59, 20, 30


If awkped reads the message:

        o 3 off

and the third line of the parameter file is:

        switch4: on

then after the edit, the resulting line will become:

        switch4: off

Ped

Parameter editor using ed.

Ped's functionality has been added to Awkped, and so continued use of Ped is no longer recommended.

Usage:

ped file_name

Description:

Ped interprets messages of the following format from stdin:

        n line field  scale value
        o line string
line: the line number to be edited,
field: the field number of a numeric value,
scale: a power of 10 scaling factor,
value: an integer number,
string: on or off.

Normally this input is piped to ped from the panel manager.

Ped uses this input to edit a parameter file containing lines of the format:

        parameter-name: value1 [, value2 [, value3 ]]
        parameter-name: string

where value1, value2, value3 are integer or floating point numbers, and string is the character string on or off.

Examples:

If ped reads the message:

        n 1 2 -2 459

and the first line of the parameter file is:

        light direction: 10, 20, 30

then after the edit, the resulting line will become:

        light direction: 10, 4.59, 30

If ped reads the message:

        o 3 off

and the third line of the parameter file is:

        switch4: on

then after the edit, the resulting line will become:

        switch4: off

References

L. Mercer. The Virtual laboratory. Master's thesis, University of Regina, Regina, Canada, 1991.

L. Mercer, P. Prusinkiewicz, J. Hanan. The Concept and Design of a Virtual Laboratory. In Graphics Interface '90 Conference proceedings, pages 149-155. Canadian Information Processing Society, 1990.

Credits

L. Mercer - panel manager implementation

L. Mercer, I. Hernadi, P. Prusinkiewicz - panel manager documentation

Bugs

1. Sliders don't slide, they merely jump to the new position where the mouse is clicked.

2. There should be a facility to allow users to build control panels interactively, using a drag and drop design method.

3. The Restore menu item brings back page 1 of the control panels, regardless of what page was being used just previously.

4. There is no way to save different sets of settings as "presets".

5. The current data file settings cannot be stored automatically into the panel definition file, manual editing is required.

6. Default values are always read from the panel definition file, settings may not be the same as what is stored in the data files.

7. There is only a one-way communication flow in the system (see Figure 1).

8. Placement of controls is referenced with respect to the bottom left corner of the control panel, hence addition of new controls below previous ones necessitates changing of coordinate values of all previous items.

9. Color indices greater than 256 result in a white background on 8-bit machines.
 


Last updated July 12th, 1999 by Pavol Federl