.. _xml_tags:
.. highlight:: xml

XML Tags 
========

Solver 
~~~~~~

The ``solver`` tag is used to describe a code to interface. It has to considerated as a container

* ``mandatory`` attributes: name, title
* ``other`` attributes: none


Tab 
~~~

The ``tab`` tag is used to describe a container within solvers. It contains all
the models related to a same subject. In C3Sm, it represents a tab.

* ``mandatory`` attributes: name, title
* ``other`` attributes: existif, script, level


Model 
~~~~~

The ``model`` tag is used as a visual container (in the GUI) and as a common node for several children (in the scripts).
Several children of any type can be added to a model. Of course, even models, xor, or multiples can be added into a model.

* ``mandatory`` attributes: name, title
* ``other`` attributes: existif, layout

The ``layout`` attribute allows to change the appearance of a model.
The ``layout="onrequest"`` makes the model collapsable, with is the best way to hide experts parameters.
The other options are seldom used, complicates the User Interaction and will probably be deprecated in a next release
* ``group_of_models`` for a metamodel (higher in the visual hierachy)
* ``sublevel_1`` for a submodel (level -1 in the visual hierarchy)
* ``sublevel_2`` for a subsubmodel (level -2 in the visual hierarchy)
* ``sublevel_3`` for a subsubsubmodel (level -3 in the visual hierarchy)
* ``flat`` to remove the box around your model. 


The following example is extreme (do not thot that at home!)::

    <model name="glob" title="glob" layout="group_of_models"  >
      
      <param name="a" type="double" default="3.14146"/>
      <param name="b" type="integer" default="42"/>
      
          
      <model name="ml1" title="LEVEL 1" layout="sublevel_1" >
          <param name="source_c3" type="string" default="aaaaa;bbbbbb;cccccc"/>  
          <desc>
              Youpi trallala
          </desc>
              <model name="ml2" title="LEVEL 2" layout="sublevel_2" >
                  <param name="source_c3" type="file" />  
              
                  <desc>
                      Depuis que je patiente dans cette chambre noire
                  </desc>
              <model name="ml3" title="LEVEL 3" layout="sublevel_3" >
                  <param name="sourcecomparo" title="source runs" type="list_double" default="a;1;b;2;c;3" ratio="0.2"/>
                  <desc>
                      La cabaaaane au fond du jaardin
                  </desc>
              </model>
              
              <model name="ml3b" title="LEVEL 3 bis" layout="sublevel_3" >
                  <param name="sourcecomparo" title="source runs" type="list_double" default="a;1;b;2;c;3" ratio="0.2"/>
                   <desc>
                     Et les murs de pouuussiere...
                  </desc>
          </model>
          </model>
      </model>
    </model>

The variable of a model is void , unless a script changes it.
The status of a model is the worst status found among the children.


Modelonoff 
~~~~~
The ``modelonoff`` tag is similar in all aspect to the ``model``, but the variable is either ``"0"`` (off) or ``"1"`` (on).
The check button on the top changes the variable.
In the "on" state, all children are visible and accessible to the scripts.
In the "off" state, all children are destroyed and not available to the scripts.



Param 
~~~~~

The ``param`` tag is used to describe a parameter in a model. A type attribute
is mandatory to specify the data type (eg integer, boolean, etc).

* ``mandatory`` attributes: name, title, type
* ``other`` attributes: existif, require, default, level

Param "Entry"
-------------

If the attibute type is on of ``string``, ``ascii``, ``integer``, ``double``,
``complex``, ``fraction``, the parameter is show as an entry.

* ``String`` is any string of charac
* ``Ascii`` is a string without " "
* ``integer``, ``double`` and ``complex`` are tested while typing
* ``fraction`` is a double btw 0 and 1

Additionnal tests can be added for numeric types (double, integer)
* ``integer_gt1`` for > 1
* ``double_le34.5`` for <= 34.5
* ``double_gt-3.1415_le3.1415``  for    -3.1415 <  AND <=3.1415

Example::

    <param name="a" title="Double greater than 3.4" type="double_gt3.4" default="3.5" />
    <param name="b" title="Integer stricly positive"  type="integer_gt0" default="1" />
    <param name="c" title="Ascii string"  type="ascii" default="azerty" />
    <param name="d" title="String"  type="string" default="Hello world" />
 
Additionnal tests can also be added for string types (string, ascii)
* ``string_strmax45`` for <= 45 chars
* ``ascii_strmin5`` for >= 5
* ``ascii_streq8``  for   =8

Example::

    <param name="d" title="Prefix"  type="string_streq8" default="A0000001" />
 

Param "Browser"
---------------

If the attibute ``type`` is either "file", "multiple_files" or "folder" , the parameter is shown as a
browser, to find a place in the visible filesystem::

    <param name="f" title="File 1"  type="file" default="tutu.xml" filter="xml;dat"/>
    <param name="mf" title="File 1toN"  type="multiple_files"  filter="md"/>
    <param name="g" title="Folder 2"  type="folder" default="tutu" />

In the case of a multiple files dilaog, files a stored in a list separated by ";". 


Param "Cluster"
---------------

Il the attribute type is of the type ``list_*`` , the parameter is shown as a table , but handlet as a dictionnary "key1 > value1       key2 > value 2       key3 > value 3
The variable is stored as a 1D key values list: ``key1;value1;key2;value2;key3;value3``
Three cases are possible

* Free clusters::

     <param name="cluster_free" title="C1" type="list_double" default="a;1;b;2;c;3"/>

Here both keys and values can be edited , and the user can add or remove the key,value pairs.

* Fixed clusters::

     <param name="cluster_fixed" title="C2" type="list_double" default="x;1;y;2;z;3" fixed="" />

Here only values can be edited, and it is impossible to add/tremove some pairs

* Dependant clusters. Widely used, these clusters are a convenient way to make case dependant dialogs::

     <param name="source_c3" type="string" default="aaaaa;bbbbb;cccccc"/>       
     <param name="cluster_dependant" title="Cluster_c3" type="list_double_lt5" default="a;0;b;1;c;2" require="source_c3" ratio="0.7"/>

The required value must be a comma separated list like ``aaaaa;bbbbb;cccccc``.
The default value will use only the "value1" for initialisation of a new key
value: in the present case  at the start the cluster wil get
``aaaaa;0.0;bbbbbbb;0.0;ccccccc;0.0``. In the last example , the additionnal
attribute ``ratio="0.7"`` is used to give more room to the keys (70%)  when
displayed.


Param "Selection"
-----------------

If the attribute type is of the type ``selection``, the parameter is shown as
list of checkboxes in a table.  This is mostly used for a case dependent
dialog, e.g. choose a subset of files among a full list.  List the cluster,
selection depends on a variable comma speparated string ``A;B;C;D``

Example::

    <param name="selsource" default="A;B;C;D" type="string"/>
    <param name="sele"  type="selection" require="selsource" />

One can make a more complex display with multiple columns.  The additionnal
fields are separated by ``#``, and cannot
contain whitespaces.  Optionally, the ``headings`` attribue can be set. Example::

    <param name="selsource" default="A1#100Kb#img;B1##pdf;C1#13Kb;D1" type="string"/>
    <param name="sele" type="selection" headings="Name#Size#Type" require="selsource" />

Finally, a single selection mode can be forced (exaclty 1 selection expected) by
adding the attribute ``selection="single"``.


Info 
~~~~

The ``info`` tag is used to describe a read-only parameter. This kind of parameter
is writeable by external tools, *i.e.* the ``opentea`` package.  There is no status
associated to Info.

* ``mandatory`` attributes: name, title, type
* ``other`` attributes: visibility

The attribute type is affecting info only if ``type="liststring"``. 
In this case, the info displays its content as a list, using ";" as list separators.
In all other cases, the info shows the content as a line of text.

Finally, since release 2.4, and unless a  ``type="liststring"``, the info can display icons:

* Green OK if the content text starts with "success".
* Red cross if the content text starts with "error".
* Orange interogation mark if the content text starts with "unsure".


Comment 
~~~~

The ``comment`` tag is used to describe a text widget. This kind of parameter
is writeable by external tools and by the GUI user. GUI user input can be disabled.

* ``mandatory`` attributes: name, title, type
* ``other`` attributes: layout, size

The attribute state is by default set to "normal". If set to "disabled", the widget cannot be set up by the user.
The attribute size is for example "1.5:3" for a widget to increase the horizontal size by 50% and vertical size by 200%.
Due to its explicit storage in the XML project, many characters such as <, \, > are removed at input.


Choice 
~~~~~~

The ``choice`` tag is used to describe a choice between different pre-defined
values. Those values are set by adding ``option`` tags in the choice element.

* ``mandatory`` attributes: name, title
* ``other`` attributes: existif, level



Option 
~~~~~~

The ``option`` tag is used to specify to the parent node (which must be a choice
tag) one option among others. The value associated to the option is defined in
an attribute "value"

* ``mandatory`` attributes: value
* ``other`` attributes: existif


Multiple 
~~~~~~~~

The ``multiple`` tag is used to describe a list of unknown elements when writing
the XML files. For example, a list of patches is unknown when
defining the GUI. This tag has got only one type of children tags: ``item_*``.
The presence of attribute ``require`` makes the difference between a list-dependant multiple and a customizable list multiple.

* ``mandatory`` attributes: name, title
* ``other`` attributes: require, subcolumns

Usage precisions : 

* ``require`` This attribute will link the multiple node with an other node, which must be a list, e.g. "patch1;patch2;patch3". The multiple items will be controlled by this list. If the require option is not provided, the Multiple is free : item can be added or removed at will.
* ``subcolumns``  Number of columns for the RHS form. By default, all the widgets are piled in a single column. If ``subcolumn = 2`` is given, the widgets will be spread among 2 colunmns, using a Z filling pattern.


Status 
~~~~~~

Status is a widget whose status is equal to its value.
Value -1 stands for *False*, 0 for *Unknown*, 1 for *true*.
It is used by scripts to force status events in the GUI.
By default, value is 0.

*Using statuses often means that the application is not Stateless, which is never a good idea.*

* ``mandatory`` attributes: name, title
* ``other`` attributes: defaults, msgerr, msgunknown, msgtrue

The  attribute ``msgerr`` (resp. ``msgunknown``, ``msgtrue``) gives the text to show when status is *false* (resp. *unknown* and *true*  )

Xor 
~~~

The ``xor`` tag describes an exclusive choice between entities. These entities
often are models. For example, this tag allows the user to choose between
models. The models are then the children of the xor node.  When more than 6
option are proposed, one should try to group the options, as shown in the
example, to 

* ``mandatory`` attributes: name, title, default
* ``other`` attributes: existif, groups

example::

   <xor name="myxor" title="My XOr" default="big_banana" groups="on">
      <model name="big_banana" title="Big Ban'"/>
      <model name="big_apple" title="Biggup"/>
      <model name="big_peach" title=" Hey baby" />
      <model name="little_banana" title ="Baba"/>
      <model name="little_apple_golden" title="A golden"/>
      <model name="little_apple_fuji" title="A fuji"/>
      <model name="little_apple_gala" title="A gala"/>
      <model name="little_peach" title="Princess peach"/>
   </xor>


Desc
~~~~

The ``desc`` tag create a descriptive content, answering to the question *where
am i?*. A weak formatting exist for images,captions and sections.  This element
is treated only inside a ``model``::

  <desc>
  ceci est une description
  [section=Introduction]
  les descriptions permettent a l'utilisateur de savoir ou il en est
  On les decore avec des figures
  [image=vachette.gif;caption=ceci est une vache]
  
  on peut egalement ajouter des listes avec la commande:
  [item=element 1 de la liste]
  [item=element 2 de la liste]
  [item=element 3 de la liste]
  </desc>


Docu
~~~~

The ``docu`` tag create a documentation content, answering to the question "what
behind the model?". A weak formatting exist for images,captions and sections.
This element is treated only inside a ``model``::

  <docu>
  ceci est une documentation
  [section=Introduction]
  les documentation permettent a l'utilisateur de savoir ou ce qu'il y a derrière le modèle
  On les decore avec des figures
  [image=vachette.gif;caption=ceci est une vache]
  
  on peut egalement ajouter des listes avec la commande:
  [item=element 1 de la liste]
  [item=element 2 de la liste]
  [item=element 3 de la liste]
  </docu>


Include
~~~~~~~

The ``include`` tag  allows the inclusion of a xor using a tree of files in a
single folder.  in a xml file , e.g.
``library/myapp/XML/mysolver/boundaries/boundaries.xml``, a xor is added using::

    <include address="myapp XML mysolver boundaries bnd_db" />

Where the xor is stored in the folder ``library/myapp/XML/mysolver/boundaries/bnd_db``.
Inside the folder, one will find:
 
* the file ``folderParameters.xml`` reading as::

      <xor name="xor_of_bnd_1" title="First Boundaries" default="bnd_a" />

* the files ``bnd_a.xml``, ``bnd_b.xml`` and ``bnd_c.xml`` reading as::

    <model name="bnd_a" title="Boundary type A" >
           <param name="p1" type="double" default="0.0"/>
           <param name="p2" type="onoff" default="0"/>
           <param name="p3" type="integer" default="10"/>
           <desc>
                   Description of boundary A
          </desc>
    </model>
  
  ::

    <model name="bnd_b" title="Boundary type B" >
           <param name="p1" type="double" default="0.0"/>
           <param name="p2" type="string" default="azerty"/>
           <desc>
                   Description of boundary B
          </desc>
    </model>

  ::

    <model name="bnd_c" title="Boundary type C" >
           <param name="p1" type="double" default="0.0"/>
           <desc>
                   Description of boundary C
          </desc>
    </model>

The whole is stricly equivalent to write literally::

  <xor name="xor_of_bnd_1" title="First Boundaries" default="bnd_a" >
    <model name="bnd_a" title="Boundary type A" >
         <param name="p1" type="double" default="0.0"/>
         <param name="p2" type="onoff" default="0"/>
         <param name="p3" type="integer" default="10"/>
         <desc>
                 Description of boundary A
        </desc>
    </model>
    <model name="bnd_b" title="Boundary type B" >
         <param name="p1" type="double" default="0.0"/>
         <param name="p2" type="string" default="azerty"/>
         <desc>
                 Description of boundary B
        </desc>
    </model>
    <model name="bnd_c" title="Boundary type C" >
         <param name="p1" type="double" default="0.0"/>
         <desc>
                 Description of boundary C
        </desc>
    </model>
  </xor>


Graphs
~~~~~~ 

With the ``graph`` tag, simple graphs can be included in the interface.

* ``mandatory`` attributes: name, title

::

  <graph name="example_graph" title=""/>

The content of the graph is specified in a long string where the different elements are separated by semi-colons.
For example, the string below creates a black curve, with a vertical line linking each point to the y-axis. The curve is labeled "An interesting curve" with an x-axis called "A great abscissa" and a y-axis titled "A wonderful ordinate".

::

  xtitle=A great abscissa;ytitle=A wonderful ordinate;color=black;type=line_toy0;name=An interesting curve;6.39225957368e-10;246;2.59304149745e-09;1477;4.54685703754e-09;2974;6.50067257762e-09;3818;8.45448811771e-09;2935;1.04083036578e-08;2996;1.23621191979e-08;3537;1.4315934738e-08;4035;1.62697502781e-08;3946;1.82235658181e-08;3263;2.01773813582e-08;2299;2.21311968983e-08;1514;2.40850124384e-08;841;2.60388279785e-08;453;2.79926435186e-08;214;2.99464590586e-08;82;3.19002745987e-08;37;3.38540901388e-08;12;3.58079056789e-08;2;3.7761721219e-08;3;

The format of the string is the following. The parameters of the plot are given first with the syntax ``parameter_name=parameter_value``. Then the coordinates of the points are given with the order ``x1;y1;x2;y2; ... xN;yN``. 

Accepted plot parameters are:

* ``name``: curve label. Can be any string.
* ``xtitle``: x-axis label. Any string.
* ``ytitle``: y-axis label. Any string.
* ``color``: line color. Accepted colors are: ``black``, ``red``, ``blue``, ``green4``.
* ``type``: line and marker style, explained in the typesection_.
* ``size``: marker size. Any integer (but be reasonable...).

Several curves can be plotted on the same graph. In this case, the data of each curve is delimited with ``#``. For example::

  color=black;type=line;name=A first curve;0.0,0.0;1.0;1.0;2.0;2.0#color=red;type=circle;name=A second curve;0.0,1.0;1.0;2.0;2.0;

.. _typesection:

The ``type`` parameter for graphs
---------------------------------

The ``type`` parameter can accept the following values:

* ``circle``: use circles as markers.
* ``square``: use squares as markers.
* ``triangle``: use triangle as markers.
* ``diamond``: use diamonds as markers.
* ``toy0``: add a vertical line towards the y-axis at each marker position.
* ``lblall``: label each point with its value.
* ``line``: add a line linking all points of the curves.
* ``lbllast``: label the last point of the set.

For example, specifying:: 

  type=triangle

will display the curve with non-connected triangular markers. 

The values can also be combined to create more complex styles::

  type=circle_line_toy0

will display a curve with circular markers, connected by a line, with a vertical line linking each marker to the y-axis.


Action
~~~~~~

The ``action`` tag is used to create a button that triggers a python script.

* ``mandatory`` attributes: name, title, script
* ``other`` attributes: status_blocking

The ``status_blocking`` attribute can have two values : yes (default) or no. If the value is yes, the tab containing the ``action`` widget cannot be processed unless the associated python script has run successfully.

Example::

  <action name="preview_duplication" title="Get a 3D preview" script="preview_duplication.py" status_blocking="no"/>