| 1 |
<HTML> |
|---|
| 2 |
<HEAD> |
|---|
| 3 |
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> |
|---|
| 4 |
<META NAME="Author" CONTENT="Christopher Just"> |
|---|
| 5 |
<META NAME="Description" CONTENT="This file describes C2 configuration and the Configuration Editor GUI."> |
|---|
| 6 |
<META NAME="GENERATOR" CONTENT="Mozilla/4.05 [en] (X11; I; IRIX64 6.4 IP30) [Netscape]"> |
|---|
| 7 |
<TITLE>Using the VRLib Configuration System</TITLE> |
|---|
| 8 |
</HEAD> |
|---|
| 9 |
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000"> |
|---|
| 10 |
|
|---|
| 11 |
<H2> |
|---|
| 12 |
Using the VRLib Configuration System</H2> |
|---|
| 13 |
This document describes the fundamentals of VRLib's extensible configuration |
|---|
| 14 |
system, and gives an introduction to CfgEdit, a graphical configuration |
|---|
| 15 |
editing utility written in Java. |
|---|
| 16 |
<H4> |
|---|
| 17 |
Contents</H4> |
|---|
| 18 |
|
|---|
| 19 |
<UL> |
|---|
| 20 |
<LI> |
|---|
| 21 |
<A HREF="#fundamentals">Configuration Fundamentals</A></LI> |
|---|
| 22 |
|
|---|
| 23 |
<LI> |
|---|
| 24 |
<A HREF="#files">Configuration Files</A></LI> |
|---|
| 25 |
|
|---|
| 26 |
<LI> |
|---|
| 27 |
<A HREF="#descriptions">ConfigChunk Descriptions</A></LI> |
|---|
| 28 |
|
|---|
| 29 |
<LI> |
|---|
| 30 |
<A HREF="#cfgedit">Using the CfgEdit tool</A></LI> |
|---|
| 31 |
</UL> |
|---|
| 32 |
|
|---|
| 33 |
<HR><A NAME="fundamentals"></A> |
|---|
| 34 |
<H3> |
|---|
| 35 |
Configuration Fundamentals - Smooth and Extra Chunky</H3> |
|---|
| 36 |
VRLib has a <I>lot</I> of configuration information; enough that a simple |
|---|
| 37 |
text-based configuration file would be an unmanageable mess. Things are |
|---|
| 38 |
a lot simpler if we can divide things into manageable pieces. |
|---|
| 39 |
|
|---|
| 40 |
<P>We call these pieces <I>ConfigChunks</I>, or <I>Chunks</I> for short. |
|---|
| 41 |
A Chunk contains the configuration information for a particular component |
|---|
| 42 |
of the system. For example, each supported input device will have a Chunk |
|---|
| 43 |
describing its setup. Another kind of Chunk describes a display device. |
|---|
| 44 |
There are many different kinds of Chunks, which store many different kinds |
|---|
| 45 |
of information. |
|---|
| 46 |
|
|---|
| 47 |
<P>To give you a better idea, here's a list of a few of the Chunks we used |
|---|
| 48 |
in a development version of the library: |
|---|
| 49 |
<UL> |
|---|
| 50 |
<LI> |
|---|
| 51 |
Display - defines a display window</LI> |
|---|
| 52 |
|
|---|
| 53 |
<LI> |
|---|
| 54 |
DisplaySystem - matches graphic pipes to X Displays</LI> |
|---|
| 55 |
|
|---|
| 56 |
<LI> |
|---|
| 57 |
IBox</LI> |
|---|
| 58 |
|
|---|
| 59 |
<LI> |
|---|
| 60 |
Flock - setup for an Ascension Flock of Birds</LI> |
|---|
| 61 |
|
|---|
| 62 |
<LI> |
|---|
| 63 |
Keyboard - stores key bindings for a keyboard-based input simulator</LI> |
|---|
| 64 |
|
|---|
| 65 |
<LI> |
|---|
| 66 |
DummyPosition - stores default orientation and position for a dummy tracker |
|---|
| 67 |
standin.</LI> |
|---|
| 68 |
</UL> |
|---|
| 69 |
Each ConfigChunk contains one or more <I>Properties</I>. A Property has |
|---|
| 70 |
a name, a type, and zero or more values. As an example, let's consider |
|---|
| 71 |
a ConfigChunk for a 3-D tracking device with a serial interface. We might |
|---|
| 72 |
choose these four properties: |
|---|
| 73 |
<UL> |
|---|
| 74 |
<LI> |
|---|
| 75 |
<B>Name</B> - a string value that provides a descriptive name for this |
|---|
| 76 |
device. <I>All</I> ConfigChunks have a Name property. They are especially |
|---|
| 77 |
useful for telling apart several ConfigChunks of the same type - like three |
|---|
| 78 |
displays named "north", "south", and "middle".</LI> |
|---|
| 79 |
|
|---|
| 80 |
<LI> |
|---|
| 81 |
<B>Serial Port</B> - the serial port to connect to. If we're using some |
|---|
| 82 |
kind of Unix system, this would be a single string value, "/dev/ttyd2" |
|---|
| 83 |
or something similar.</LI> |
|---|
| 84 |
|
|---|
| 85 |
<LI> |
|---|
| 86 |
<B>Serial Speed</B> - the speed of the serial connection; probably a single |
|---|
| 87 |
integer value.</LI> |
|---|
| 88 |
|
|---|
| 89 |
<LI> |
|---|
| 90 |
<B>Position Offset</B> - this might be an offset from the physical tracker |
|---|
| 91 |
origin to some logical origin of your choice. We probably want a floating |
|---|
| 92 |
point value for this property, but unlike our other examples, we want three |
|---|
| 93 |
of them, for x, y, and z offsets. Any property can have multiple values, |
|---|
| 94 |
but they must all be of the same type.</LI> |
|---|
| 95 |
</UL> |
|---|
| 96 |
|
|---|
| 97 |
<H4> |
|---|
| 98 |
Property Details</H4> |
|---|
| 99 |
Before we continue, let's take a closer look at the individual parts of |
|---|
| 100 |
a Property. |
|---|
| 101 |
<UL> |
|---|
| 102 |
<H4> |
|---|
| 103 |
Name</H4> |
|---|
| 104 |
The name of a property is simply a text string used to refer to it by the |
|---|
| 105 |
GUI, like "Serial Port" or "X Display Name". |
|---|
| 106 |
<H4> |
|---|
| 107 |
Token</H4> |
|---|
| 108 |
The token is a lot like the name, and they are often the same string. The |
|---|
| 109 |
difference is that the token is used internally, in the config file format, |
|---|
| 110 |
and in the library itself when querying the configuration database. The |
|---|
| 111 |
token is restricted in a way similar to C/C++ variable names: no whitespace |
|---|
| 112 |
is permitted, and it may not begin with a number. |
|---|
| 113 |
<H4> |
|---|
| 114 |
Type</H4> |
|---|
| 115 |
There are four primitive types for properties: strings, integers, floating-point |
|---|
| 116 |
numbers, and booleans. In addition to these four types, Property values |
|---|
| 117 |
can also refer to other ConfigChunks. Example: The ConfigChunk for "general |
|---|
| 118 |
setup" might have a Property that lists the active Displays. The type for |
|---|
| 119 |
this Property could just be a string (matching the name of a Display ConfigChunk), |
|---|
| 120 |
but we can also make the Property type be "name of a Display ConfigChunk". |
|---|
| 121 |
This lets the GUI be a little smarter and easier to use when editing that |
|---|
| 122 |
property - but more on that later. |
|---|
| 123 |
<H4> |
|---|
| 124 |
Number</H4> |
|---|
| 125 |
Most Properties have single values. Other times, as with our "Position |
|---|
| 126 |
Offset" example, a Property may need a fixed number of values. It is also |
|---|
| 127 |
possible for a Property to have a variable number of values; the list of |
|---|
| 128 |
active Displays mentioned above would be a good example. There may be no |
|---|
| 129 |
active displays, there may be 6, or 2, or just 1. |
|---|
| 130 |
<H4> |
|---|
| 131 |
Value Lists (optional)</H4> |
|---|
| 132 |
Sometimes a Property might have a certain number of appropriate choices. |
|---|
| 133 |
For example, the handedness of a glove is either "Left" or "Right", and |
|---|
| 134 |
it would be nice if our GUI could display those as choices to the user, |
|---|
| 135 |
instead of requiring them to type in a string. The configuration system |
|---|
| 136 |
supports this with enumerations, which are simply lists of the appropriate |
|---|
| 137 |
values for a Property. Enumerations for string Properties are just lists |
|---|
| 138 |
of string values, while enumerations for integer and float Properties map |
|---|
| 139 |
descriptive strings to numeric values.</UL> |
|---|
| 140 |
|
|---|
| 141 |
<HR><A NAME="files"></A> |
|---|
| 142 |
<H3> |
|---|
| 143 |
Configuration Files</H3> |
|---|
| 144 |
The configuration information for a VRLib application is stored in several |
|---|
| 145 |
files: |
|---|
| 146 |
<UL> |
|---|
| 147 |
<LI> |
|---|
| 148 |
The <I>Global</I> config file contains a basic configuration. The global |
|---|
| 149 |
file should be enough to get an application running; it should contain |
|---|
| 150 |
all of the basic hardware setup information.</LI> |
|---|
| 151 |
|
|---|
| 152 |
<LI> |
|---|
| 153 |
The <I>User</I> config files are used to modify and add to a basic configuration.</LI> |
|---|
| 154 |
|
|---|
| 155 |
|
|---|
| 156 |
<P>A user's config files are stored in the <TT>.C2Config</TT> directory |
|---|
| 157 |
of the user's home directory. A user can have as many different User config |
|---|
| 158 |
files as he or she desires. There may be different User config files for |
|---|
| 159 |
different applications, or maybe one that sets up a particular set of simulator |
|---|
| 160 |
devices.</UL> |
|---|
| 161 |
When a VRLib application is initialized, it creates an internal database |
|---|
| 162 |
of config information. The ConfigChunks defined in the Global config file |
|---|
| 163 |
are added into the database, followed by the Chunks in a specified User |
|---|
| 164 |
config file (<TT>~/.C2Config/default</TT> if none is specified). If a Chunk |
|---|
| 165 |
in the User file has the same name as a Chunk in the Global file, it replaces |
|---|
| 166 |
the previously-read Global Chunk. |
|---|
| 167 |
|
|---|
| 168 |
<P> |
|---|
| 169 |
<HR> |
|---|
| 170 |
<H4> |
|---|
| 171 |
ConfigChunk Descriptions</H4> |
|---|
| 172 |
The configuration system is itself configurable. A separate file lists |
|---|
| 173 |
all the available kinds of ConfigChunks, what their Properties are, wether |
|---|
| 174 |
these Properties have enumerations, and so on. These <I>ChunkDescs</I> |
|---|
| 175 |
can also be edited by the GUI. |
|---|
| 176 |
|
|---|
| 177 |
<P>Because the ConfigChunk descriptions can be edited by users and developers, |
|---|
| 178 |
applications built on VRLib can use this configuration system to handle |
|---|
| 179 |
their own setup information. All that is needed is to add an "ApplicationData" |
|---|
| 180 |
ChunkDesc with the appropriate Properties, and put a Chunk of that type |
|---|
| 181 |
in one of the configuration files. This can all be done through the GUI. |
|---|
| 182 |
VRLib provides an interface for the client application itself to access |
|---|
| 183 |
this data. |
|---|
| 184 |
|
|---|
| 185 |
<P> |
|---|
| 186 |
<HR><A NAME="cfgedit"></A> |
|---|
| 187 |
<H3> |
|---|
| 188 |
The CfgEdit tool</H3> |
|---|
| 189 |
blah blah blah java yadda yadda |
|---|
| 190 |
<H4> |
|---|
| 191 |
Installing CfgEdit</H4> |
|---|
| 192 |
|
|---|
| 193 |
<OL> |
|---|
| 194 |
<LI> |
|---|
| 195 |
Make sure you have installed on your system the Java Development Kit (JDK), |
|---|
| 196 |
version 1.1.3 or higher. <A HREF="http://java.sun.com/products/jdk/">Sun's |
|---|
| 197 |
JDK index page</A> has information about obtaining the JDK for various |
|---|
| 198 |
operating systems.</LI> |
|---|
| 199 |
|
|---|
| 200 |
<LI> |
|---|
| 201 |
Make a directory for the CfgEdit files. For demonstration purposes, we'll |
|---|
| 202 |
use the directory <TT>/bin/cfgedit</TT>.</LI> |
|---|
| 203 |
|
|---|
| 204 |
<LI> |
|---|
| 205 |
Copy the following files into the directory you just made:</LI> |
|---|
| 206 |
|
|---|
| 207 |
<PRE>CfgEdit |
|---|
| 208 |
c2cfg.html |
|---|
| 209 |
c2cfg.jar</PRE> |
|---|
| 210 |
|
|---|
| 211 |
<LI> |
|---|
| 212 |
CfgEdit is a very short script file that can be used to execute the CfgEdit |
|---|
| 213 |
tool from any directory. However, it needs to be told how to find the .jar |
|---|
| 214 |
file which contains the actual java code. To do this, find this line in |
|---|
| 215 |
the file:</LI> |
|---|
| 216 |
|
|---|
| 217 |
<PRE>java -classpath /bin/cfgedit/c2cfg.jar:$JDK_HOME/lib/classes.zip AppCore</PRE> |
|---|
| 218 |
Change the path to c2cfg.jar to whatever directory you moved the files |
|---|
| 219 |
to in step 2. |
|---|
| 220 |
<LI> |
|---|
| 221 |
Before running CfgEdit for the first time, create a directory called <TT>.C2Config</TT> |
|---|
| 222 |
in your home directory. This will be used to store your User config files.</LI> |
|---|
| 223 |
|
|---|
| 224 |
<LI> |
|---|
| 225 |
Inside the <TT>.C2Config</TT> directory, create a file called <TT>basedir</TT>. |
|---|
| 226 |
This file should contain one line: the name of the directory where the |
|---|
| 227 |
Global config and ChunkDesc files are located. (This depends on where you |
|---|
| 228 |
installed the rest of VRLib).</LI> |
|---|
| 229 |
</OL> |
|---|
| 230 |
|
|---|
| 231 |
<H4> |
|---|
| 232 |
Running CfgEdit</H4> |
|---|
| 233 |
Once installed, CfgEdit can be executed either as an application or as |
|---|
| 234 |
an applet. |
|---|
| 235 |
|
|---|
| 236 |
<P>To run as an application, simply run the CfgEdit script. The script |
|---|
| 237 |
accepts the name of a User ConfigChunk file as an argument. |
|---|
| 238 |
|
|---|
| 239 |
<P>To run as an applet, type <TT>appletviewer /bin/cfgedit/c2cfg.html</TT> |
|---|
| 240 |
(or whatever the correct path to the html file is). While it is currently |
|---|
| 241 |
easiest to run CfgEdit as an application, using the script, we hope to |
|---|
| 242 |
soon be able to run the applet from various web browsers. |
|---|
| 243 |
|
|---|
| 244 |
<P>As soon at it begins, CfgEdit checks the user's .C2Config/basedir file |
|---|
| 245 |
to determine where the global configuration files are. It then loads files |
|---|
| 246 |
in this order: |
|---|
| 247 |
<OL> |
|---|
| 248 |
<LI> |
|---|
| 249 |
The Global ChunkDesc file, chunkDescs in the basedir.</LI> |
|---|
| 250 |
|
|---|
| 251 |
<LI> |
|---|
| 252 |
The user's User ChunkDesc file, .C2Config/chunkDescs (currently unimplemented).</LI> |
|---|
| 253 |
|
|---|
| 254 |
<LI> |
|---|
| 255 |
The Global ConfigChunk file, <TT>C2config</TT> in the basedir.</LI> |
|---|
| 256 |
|
|---|
| 257 |
<LI> |
|---|
| 258 |
One of the user's User ConfigChunk files, if one was specified.</LI> |
|---|
| 259 |
</OL> |
|---|
| 260 |
The window that CfgEdit opens has two parts. On the left side is a list |
|---|
| 261 |
of the available panels. Double-click on one of the names on the list to |
|---|
| 262 |
show that panel in the right side of the window. Currently, there are two |
|---|
| 263 |
available panels, one for editing ChunkDesc files and one for editing ConfigChunk |
|---|
| 264 |
files. |
|---|
| 265 |
<H4> |
|---|
| 266 |
Editing ConfigChunks</H4> |
|---|
| 267 |
You can access a list of all ConfigChunks in the DB by double-clicking |
|---|
| 268 |
on "Chunks" in the Panels list. The list is sorted by type of chunks, so |
|---|
| 269 |
that all the Display chunks are listed together, and so on. |
|---|
| 270 |
|
|---|
| 271 |
<P>The Global config file is usually loaded by default. In addition, you |
|---|
| 272 |
can load a User config file on top of the Global file, so that all the |
|---|
| 273 |
different Chunks in both files are displayed in the list. |
|---|
| 274 |
|
|---|
| 275 |
<P>Once you have modified one or more Chunks, there are several options |
|---|
| 276 |
for saving your work. Using the "Save Global Config" menu option writes |
|---|
| 277 |
the entire contents to the file C2config in the directory given by basedir. |
|---|
| 278 |
Of course, you may not have permission to write that file, so there is |
|---|
| 279 |
also a "Save Global Config As" option which lets you enter a filename. |
|---|
| 280 |
|
|---|
| 281 |
<P>You can also save just those Chunks which differ from the Global config |
|---|
| 282 |
file. You do this with the "Save User Config" and "Save User Config As" |
|---|
| 283 |
menu items, or with the "Save" button to the right of the list of Chunks. |
|---|
| 284 |
User config files are always written to the user's .C2Config directory, |
|---|
| 285 |
and always have the suffix ".cfg" added to them. |
|---|
| 286 |
|
|---|
| 287 |
<P>Once you've loaded the config files you want to deal with, you can look |
|---|
| 288 |
at and edit the configuration. There are several buttons to the right of |
|---|
| 289 |
the list of Chunks which help you do this: |
|---|
| 290 |
<UL> |
|---|
| 291 |
<LI> |
|---|
| 292 |
Insert - inserts a new ConfigChunk. The menu button to the right of the |
|---|
| 293 |
Insert button lets you choose the type of ConfigChunk that will be inserted.</LI> |
|---|
| 294 |
|
|---|
| 295 |
<LI> |
|---|
| 296 |
Remove - you can remove a ConfigChunk by selecting it from the list and |
|---|
| 297 |
then pressing this button.</LI> |
|---|
| 298 |
|
|---|
| 299 |
<LI> |
|---|
| 300 |
Clear - removes all ConfigChunks.</LI> |
|---|
| 301 |
|
|---|
| 302 |
<LI> |
|---|
| 303 |
Load - does the same thing as the "Load User Config" menu option.</LI> |
|---|
| 304 |
|
|---|
| 305 |
<LI> |
|---|
| 306 |
Save - does the same thing as the "Save User Config" menu option.</LI> |
|---|
| 307 |
</UL> |
|---|
| 308 |
Double-clicking on a Chunk's name in the list will bring up a new window, |
|---|
| 309 |
displaying the Chunk's name and a list of all its properties. A text field |
|---|
| 310 |
at the top of the window lets the user change the Chunk's name. |
|---|
| 311 |
|
|---|
| 312 |
<P>A scrolling list in the middle of the window displays all of the available |
|---|
| 313 |
properties. Each property is listed with its name, type, and values. A |
|---|
| 314 |
line of help information is also displayed if available. The user can edit |
|---|
| 315 |
the displayed values. If the property is of boolean type, or has a list |
|---|
| 316 |
of acceptable values, the value is displayed with a pop-up list, from which |
|---|
| 317 |
the user can choose a new value. Otherwise, the current value is displayed |
|---|
| 318 |
in a text field, in which the user can enter a new numeric or string value. |
|---|
| 319 |
|
|---|
| 320 |
<P>Press the OK button to close the window and save any changes. Press |
|---|
| 321 |
Cancel or the close button to get rid of the window without making any |
|---|
| 322 |
changes. Of course, nothing happens to the files on disk until you specifically |
|---|
| 323 |
save them. |
|---|
| 324 |
<H4> |
|---|
| 325 |
Editing Chunk Descriptions</H4> |
|---|
| 326 |
You can edit the list of Chunk descriptions by double-clicking on "Descriptions" |
|---|
| 327 |
in the Panels list. The panel that shows up looks and functions very similarly |
|---|
| 328 |
to the ConfigChunk panel; it has the same buttons which perform the same |
|---|
| 329 |
functions, and an analogous set of menu items. The key difference is that |
|---|
| 330 |
while there can be multiple User ConfigChunk files in the .C2Config directory, |
|---|
| 331 |
there is only one ChunkDesc file - .C2Config/chunkDescs . |
|---|
| 332 |
|
|---|
| 333 |
<P>The Window for editing a ChunkDesc is much like the window for editing |
|---|
| 334 |
a ConfigChunk. The main difference is the addition of "Insert" and "Remove" |
|---|
| 335 |
buttons to add and get rid of individual property descriptions. |
|---|
| 336 |
|
|---|
| 337 |
<P>The ConfigChunk Window had a scrolled list of Properties; the ChunkDesc |
|---|
| 338 |
Window has a scrolled list of Property descriptions. Each property description |
|---|
| 339 |
has several fields. The first two are for "Name" and "Token". "Name" is |
|---|
| 340 |
the string the library or an application will use to access that property. |
|---|
| 341 |
"Token" is the string that will be used inside the config file. Most likely |
|---|
| 342 |
you'll want these to be the same, but they don't have to be. The major |
|---|
| 343 |
limitation is that you may not use white space characters int the Token |
|---|
| 344 |
field. |
|---|
| 345 |
|
|---|
| 346 |
<P>Next there is a field to enter the number of values you want this property |
|---|
| 347 |
to have, and a checkbox to select if you want the property to have a variable |
|---|
| 348 |
number of values. There is also a text field to enter a help message describing |
|---|
| 349 |
what the values for this property mean. |
|---|
| 350 |
|
|---|
| 351 |
<P>Finally, there is a pulldown list to select the type of this property |
|---|
| 352 |
(String, Integer, Float, Boolean, or Chunk), and a button marked |
|---|
| 353 |
<HR> |
|---|
| 354 |
<H2> |
|---|
| 355 |
Known Bugs</H2> |
|---|
| 356 |
|
|---|
| 357 |
<UL> |
|---|
| 358 |
<LI> |
|---|
| 359 |
If you create or load a ChunkDesc for a type "foo", and create a ConfigChunk |
|---|
| 360 |
of that type, and then edit the ChunkDesc for "foo", the effect on the |
|---|
| 361 |
extant ConfigChunks is not defined. They <I>ought</I> to cleanly adapt |
|---|
| 362 |
to the new ChunkDesc. What will currently probably <I>happen</I> is that |
|---|
| 363 |
the Chunk will retain the old description, save itself according to that |
|---|
| 364 |
description, and cause a parse error when it's reloaded.</LI> |
|---|
| 365 |
|
|---|
| 366 |
|
|---|
| 367 |
<P>Reccommended fix: delete all chunks of type "foo" before changing the |
|---|
| 368 |
description. In practice, ChunkDescs aren't edited often. |
|---|
| 369 |
<LI> |
|---|
| 370 |
There should be a way for users to define their own ChunkDescs in a file |
|---|
| 371 |
in their own directory (much like the Global/User config files). Currently, |
|---|
| 372 |
if a user wants to add a new type of ConfigChunk for an application they |
|---|
| 373 |
are creating, the ChunkDesc must be added to the global ChunkDesc file.</LI> |
|---|
| 374 |
|
|---|
| 375 |
<LI> |
|---|
| 376 |
While CfgEdit lets you create value lists for float type Properties, the |
|---|
| 377 |
Config system in VRLib itself doesn't support these correctly yet.</LI> |
|---|
| 378 |
</UL> |
|---|
| 379 |
|
|---|
| 380 |
</BODY> |
|---|
| 381 |
</HTML> |
|---|
