The static method vwWidget::parseWdgConfig() can be used to facilitate the construction of interfaces. In normal circumstances it would be called from the concrete mediator's createWidgets() method. Below is a description of the file structure parseWdgConfig() expects.

The configuration file can be broken up into three sections. The first and second sections are mandatory. The optional third section can be used for describing widget labeling.

The first line of the file is the header. All configuration files must have a header. The first character of the first line must be a '#'  followed by a space followed by a string that specifies the name of the configuration file. This string should have no commas, spaces or tabs. The remainder of the first line should be blank. This header string can be used by the concrete mediator to determine which type of interface has been parsed. This is helpful in the case where a concrete mediator handles numerous interfaces. After the header line, all lines beginning with a '#' are parsed as comments. Blank lines are skipped.

The rest of section one is optional transformation and color information. If no transformations are specified, the interface pfDCS will have a unity transform. The transformation matrix that describes the interface pfDCS is know as Interface Coordinate Space. If no colors are specified, default colors will be used. Key words for transformations and colors are described below. All of these key words must be followed by three space delimited float values. Translation, rotation and scale are specified according to a right-handed rule with Y up, X right, and Z towards the viewer. Conversions to Performer's Z-up coordinate system are made internally.

#Translate 5 in X, 3 in Y, 0 in Z.
Translation     5.0 3.0 0.0
#in HPR Z's sign is changed internally for right-handed rotation with Performer
#Rotate in Heading, Pitch, Role of 0 in H, -43.5 in P, 0 in R
Rotation           0.0 -43.5 0.0
#Scale of 0.5 in X, 1.0 in Y, 0.5 in Z
Scale                0.5 1.0 0.5

#Colors are specified as RGB (0.0 to 1.0)
ActiveColor           0.0 0.3 0.5
InactiveColor        0.2 0.2 0.2
OverColor             0.0 1.0 0.25
PickedColor          1.0 1.0 0.0
# Color a picked widget changes (e.g., pressed button) when getOver() is True.
PickedOverColor 1.0 0.15 0.0
# Color for label text
LabelColor            1.0 1.0 1.0

Section two describes the widgets that will make up the interface. Normally a widget can be completely described in one line consisting of six fields, the last two of which have three components each. The one exception to this is a vwButton with a child interface. In that situation, the path to the child interface configuration file is placed in the line immediately below the parent vwButton. The path is followed by a space or tab and the key-word LOAD_DELAY. LOAD_IMMEDIATE is not yet implemented. The current implementation supports only one child interface and only widgets of type vwButton can have a child.

With all but widgets of type vwSlider, the widget's description line takes the following form.
Base_Name  Geomfile_Name Ident_Keyword Num_Children Translation(3) Scale(3)

Base_Name. The Base_Name is a keyword that specifies the generic widget class of whom the widget being described is a type. See isOfType().
BUTTON                          (belongs to vwButton)
SLIDER                            (belongs to vwSlider)
FRAME                            (belongs to vwFrame)
INCREMENTOR            (belongs to vwIncrementor)

Geomfile_Name. The name of the geometry file to be loaded for this widget.

Ident_Keyword. The Ident_Keyword is a user defined term that should indicate something about this particular widget's job. Since it is user defined, the concrete mediator must in most circumstances have a priori knowledge of it. Ident_Keyword should not contain spaces, commas or tabs. The Ident_Keyword should be unique (i.e., no two widgets in the same interface should have the identical Ident_Keyword). If the widget is to have a label, it can be specified in Section Three of the configuration file using the Ident_Keyword to specify the owner of the label.

Num_Children. The Num_Children field should contain an integer value of 0 unless the widget being described has a Base_Name of BUTTON and there is a child interface for this BUTTON. The SLIDER special case also differs. It will be described later.

Translation(3). The Translation field is made up of three space delimited floating point numbers specifying the translation that will be applied the the widget's pfDCS or pfSCS.

Scale(3). The Scale field is made up of three space delimited floating point numbers specifying the scale that will be applied the the widget's pfDCS or pfSCS.

Let's take a look at an example button description row:
BUTTON   interface_button.iv    DOSOMETHING    1    0.0 2.0 0.0    1.0 0.5 1.0
                                                ./etc/simulator.dosomething.config      LOAD_DELAY

With widgets of type vwSlider, the widget's description line takes a slightly different form.
Base_Name  Geomfile_Name Ident_Keyword AXIS TranslationAndRange(3) Scale(3)

The first three fields and the last (Scale) are identical to those with other widget types. In the current implementation, vwSlider geometry consists only of a pfDCS that moves along an axis. It does not include a base or frame that one would normally associate with sliders per-se. This decision was the result of ease-of-implementation, consistency, and modularity concerns. Therefore, it is strongly recommended that each slider be accompanied by a vwFrame. A future implementation may integrate a frame geometry into the vwSlider class. A slider will work without a frame. But not well. It is all but impossible to keep the wand pointer on a small sliding geometry in any smooth fashion. A backing frame in the same interface coordinate space allows intersection information to continue to update the slider's position even while the wand vector is not intersecting the slider geometry.

AXIS. AXIS is a keyword that specifies the axis of motion for the slider in local coordinates. Valid keywords are X, Y, or Z. X will give you a horizontal slider in local coordinates. Y will give you a vertical slider in local coordinates. Z will give you a to and away slider in local coordinates.

TranslationAndRange. This field is specified by three space delimited floating point values. Range specifies the range of motion of the slider in interface coordinates. Therefore, if a  Y slider is meant to exactly span a unit-sized frame in the same interface which has been scaled by 5.0 in Y, the slider's Range should be set to 5.0. Where the Range goes is determined by the value in the AXIS field. If AXIS is X, Range is the first of the three floats. If AXIS is Y, Range is second. And if AXIS is Z, Range is the third float value. The remaining two float values specify slider translation in the two other axises in local coordinates.

Let's take a look at an example slider description row:
SLIDER   interface_slider.iv    SLIDESOMETHING   X    1.0 3.5 0.5    1.0 0.5 1.0

SECTION THREE (optional)
Section three describes label text for any widgets described section two. One line per label.

The label description line takes the following form.
Ident_Keyword Total_Words Total_Rows Word_List

Ident_Keyword matches that of the widget described in section two who's label is now being described.

Total_Words (a number) is the total number of words specified for the label (6 max).

Total_Rows (a number) is the total number of rows specified for the label (3 max).

Word_List is made up of a space delimited group of word-rows. Each word-row consists of a string followed by a comma followed by a number that specifies which row the string belongs to. Word_List should begin with row one and move from left to right. Then the same for row two (if there is a second row). Then the same for row three (if there is a third). Row skipping from 1 to 3, not beginning with 1, or any other such shenanigans will bring about undesirable results (i.e., core dump;^).

Let's take a look at an example label description row:

ExampleConfigfile, README.config

vrmedlab.jpg (7272 bytes)