VWLib REFERENCE MANUAL
CONFIGURATION FILE FORMAT- 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.
SECTION ONE- 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- 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:
- DOSOMETHING 3 2
DO,1 SOMETHING,1 INTERESTING,2
SEE ALSO- ExampleConfigfile, README.config
