Ryzom

h1. Georges Form

h2. Introduction 

Georges is a versatile and flexible form loader built upon XML. A basic Georges form is comprised of three basic elements:

* The *Form* itself.

* The *Definition* (DFN) files.

* And *Type* (TYP) definitions.

To better understand how the pieces of a form come together it is easiest to learn the files in reverse order. Forms rely on definitions which rely on types. A type is the simplist piece of configuration in a Georges form.

h2. Types

Types are the smallest block of information in creating a Georges form. Before doing anything else you will need a set of basic types and an understanding of creating custom ones for your data types. First we'll show you two samples. These are types that can be used in a real application but are simple enough to see the basics of a type and give some examples elements to describe.

* int.typ - A basic integer.

<pre><code class="CPP"><?xml version="1.0"?>

<TYPE Type="SignedInt" UI="EditSpin" Default="0" Min="-9223372036854775808" Max="9223372036854775807">

</TYPE></code></pre>

* boolean.typ - A basic boolean.

<pre><code class="CPP"><?xml version="1.0"?>

<TYPE Type="String" UI="NonEditableCombo" Default="false">

  <DEFINITION Label="true" Value="true"/>

  <DEFINITION Label="false" Value="false"/

</TYPE></code></pre>

All type files should contain only one TYPE element but can contain several DEFINITION elements under TYPE. You can place other elements inside of a TYPE tag. For example some of the NeL tools will add a COMMENT and a LOG entry into the block to track changes on the type. Most of the properties of a type are self explanatory, but the DEFINITION elements need some extra commentary. DEFINITION's have a Label and a Value. The Label is the information used in form comparison and validation. The Value is what is returned when an atom is requested via the API for an atom matching that label. This is a way to create a list of valid values that don't adhere to minimum and maximum, for example the string-based boolean type above.

All types can contain the following properties:

    * Type - the type of data this will return. All Types must have this property.

    * UI - the type of UI widget an editor would use to edit this. All Types must have this property.

    * Default - the default value of elements/atoms using this data type.

    * Min - For numeric types the minimum valid value.

    * Max - For numeric types the maximum valid value.

    * Increment - For numeric values the increments the UI should edit in.

There are a number of valid data types a type can provide, they are:

    * UnsignedInt

    * SignedInt

    * Double

    * String

    * Color

The following are valid UI types that Georges will parse and provide to any tools using it:

    * Edit

    * EditSpin

    * NonEditableCombo

    * FileBrowser

    * BigEdit

    * ColorEdit

h2. Definitions

Definitions define the types of arrays, structures and atoms available in the form and the type of information they provide. All forms require one definition file at the minimum, the first definition file is loaded based upon the form's file extension. For example if your form file is named sample.config_data Georges will load the config_data.dfn definition file (and any definitions or types it utilizes) before it processes the form data. Definition files have two main elements:

    * ELEMENT - this describes the data contained in an array, struct, or atom.

    * PARENT - this forces a definition to load other definitions as dependencies. This is handy of you have some often-used atoms.

Lets see an example definition file:

sample_config.dfn

<pre><code class="CPP"><?xml version="1.0"?>

<DFN>

        <ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/>

        <ELEMENT Name="TestVal2" Type="Type" Filename="int.typ" Default="0"/>

        <ELEMENT Name="WriteVal" Type="Type" Filename="int.typ" Default="0" />

        <ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/>

        <ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/>

        <ELEMENT Name="TestByBracket" Type="Type" Filename="boolean.typ" Array="true"/>

        <ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" />

</DFN></code></pre>

Elements are the most complicated piece of a definition as they have a number of variations depending on the type of data their atoms, etc. would contain. Elements with a type of "Type" will represent atoms that contain values. Elements require a Name, Type, and Filename property at the minimum. Elements represent three different types of data types: structs, arrays, and atoms. If you look ahead to forms, these different types of data may make more sense. In the XML above we see five examples of atom types, two arrays, and a structure. You can see the full set of these files in the sample in CVS, it may help make some of this make more sense.

h3. Elements for Atoms

When setting up an element for an atom you need to name it  (this is the name will be the one that the atom will use in the form,) you need to define it's type as "Type," and you need to define a filename. The filename defines the type of data (see types, above) any atoms using this element will use. Elements for atoms are the most simple types of element definitions. Note that you can also set the default value for an atom here, overriding the default value defined by the type.

<pre><code class="CPP"><ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/></code></pre>

h3. Elements for Structs

In our example we also define a named struct. In the form when you do _<STRUCT Name="_PositionData">_ you need to create an element to describe this struct. Here is the example from above:

<pre><code class="CPP"><ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" /></code></pre>

The name of the element must match the name of the struct in the form. You will set your type to Dfn and define the definition file's filename in the Filename property. This tells Georges this is a struct and how to determine what atoms are members of it. Finally you need to flag Array="false" so that Georges knows it's just one struct, not a named array of them.

h3. Elements for Arrays

There are two types of arrays to consider when creating an element entry for an array.

*Arrays of Atoms*

Arrays of atoms are the easiest types of array to define. Take the following snippet from the definition example above:

<pre><code class="CPP"><ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/></code></pre>

In essence what we've done was created an element definition for an atom and used the Array="true" property to tell Georges to expect a list of strings. You'll see an example of defining this array in the section on creating and editing forms.

*Arrays of Structs*

An array of structs is slightly more complicated, but still fairly simple in syntax. Instead of defining the type as "Type" you would define it as "Dfn." This tells Georges that it should expect a list of structures containing the elements listed in the Filename. Look at the following snippet from the XML above:

<pre><code class="CPP"><ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/></code></pre>

We've informed Georges here that an array named "CoolFilesInfo" is going to contain a list of structs with the info contained in the definition file "coolfilesinfo.dfn." The sample for Georges in CVS contains that file and some code on accessing it through the Georges API.

h3. Element Information

Elements contain the following properties.

    * Name - the name of the element as it will be used in the form.

    * Filename - the filename of the file to be loaded to define this element's type.

    * FilenameExt - _I'm not sure what this is for, it defaults to "." and isn't used anywhere else in Georges or any of the tools or samples._

    * Type - specifies the type of dependency this element has for its type.

    * Default - specifies the default value for this element.

    * Array - this is a true/false string. This says that the form is going to specify multiple items of this element type in an array.

Valid Element Type values are:

    * Type - if this value is specified the definition loads the TYPE specified in the Filename property of the Element.

    * Dfn - for structs and arrays, defining the atoms they will contain.

    * DfnPointer - _I'm not sure what this is used for._

h2. Forms

Using the information from above about types and definitions you can finally get down to working on creating your form. Below is a trimmed down version of the form used in the Georges sample from SVN. Notice that the file extension of the form below is the filename of the extension list above in the definitions section.

default.sample_config

<pre><code class="CPP"><?xml version="1.0"?>

<FORM Version="0.0" State="modified">

        <STRUCT>

                <ATOM Name="TestVal1" Value="1"/>

                <ARRAY Name="TestArray">

                        <ATOM Value="Array Val 1"/>

                        <ATOM Value="Array Val 2"/>

                </ARRAY>

                <ARRAY Name="CoolFilesInfo">

                        <STRUCT>

                                <ATOM Name="ShortName" Value="Tiger Attack"/>

                                <ATOM Name="Ranking" Value="55"/>

                        </STRUCT>

                        <STRUCT>

                                <ATOM Name="ShortName" Value="Crazy Car Jump"/>

                                <ATOM Name="Ranking" Value="40"/>

                        </STRUCT>

                </ARRAY>

                <STRUCT Name="PositionData">

                        <ATOM Name="x" Value="1"/>

                        <ATOM Name="y" Value="1"/>

                        <ATOM Name="z" Value="2"/>

                </STRUCT>

        </STRUCT>

</FORM></code></pre>

Looking at the example form above you should start to see how forms reference elements in definitions. Some important things to note about forms. The first element must always be either a STRUCT or a PARENT and parents should come before STRUCTs. You should never put any other element type directly under a FORM. In the code example you will see that you can access the ATOMs in the first (default) struct by refering to them in dot notation such as ''".TestVal1"'' - the dot denotes they're a member of the root structure.

h3. Atoms

ATOMs represent individual data types, they define values you will use in your application. Atoms all have a Name property and a Value property. A name for an atom may be left out only if it is a member of a named array. Look at the ''TestArray'' example - the atoms contained in that array inherit their name (and thus element info) from the array.

h3. Arrays

Arrays in a form are simple. All they require is a name. This name allows Georges to find the element type from the definition and thus atom or definition information required to describe the items in the array. In the example above I provided two types of arrays. An array of structures and an array of atoms. Building these in the form is as straight forward as the example. Building the definitions is explained above in the definitions section. Arrays can be accessed programmatically by their name as well using bracket and bracket/dot notation. In the case of ''TestArray'' you can access the data using ''TestArray'' and in the case of ''CoolFilesInfo''  you could access it's member data as ''CoolFilesInfo.Ranking'' - examples of processes like this are given in the code sample.

h3. Structs

Structs are used in a number of ways already described in detail. But they can also be used in a standalone type to be accessed in dot notation as described in the arrays section. You can see this in the ''PositionData'' example in the form. Members of this structure can programmatically be accessed via the root node using the name ''PositionData.x'' or any of the other members.

h3. Form Information

Forms contain the following elements:

    * ATOM

    * STRUCT

    * VSTRUCT

    * ARRAY

    * And PARENT