4.3.1. XML Tags¶

4.3.1.1. 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

4.3.1.2. 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

4.3.1.3. 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.

4.3.1.4. 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.

4.3.1.5. 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

4.3.1.5.1. 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" />

4.3.1.5.2. 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 “;”.

4.3.1.5.3. 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.

4.3.1.5.4. 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".

4.3.1.6. 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”.

4.3.1.7. 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.

4.3.1.8. 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

4.3.1.9. 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

4.3.1.10. 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.

4.3.1.11. 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 )

4.3.1.12. 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>

4.3.1.13. 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>

4.3.1.14. 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>

4.3.1.15. 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>

4.3.1.16. 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;

4.3.1.16.1. 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.

4.3.1.17. 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"/>

Navigation

Related Topics

4.3.1. XML Tags¶

4.3.1.1. Solver¶

4.3.1.2. Tab¶

4.3.1.3. Model¶

4.3.1.4. Modelonoff¶

4.3.1.5. Param¶

4.3.1.5.1. Param “Entry”¶

4.3.1.5.2. Param “Browser”¶

4.3.1.5.3. Param “Cluster”¶

4.3.1.5.4. Param “Selection”¶

4.3.1.6. Info¶

4.3.1.7. Comment¶

4.3.1.8. Choice¶

4.3.1.9. Option¶

4.3.1.10. Multiple¶

4.3.1.11. Status¶

4.3.1.12. Xor¶

4.3.1.13. Desc¶

4.3.1.14. Docu¶

4.3.1.15. Include¶

4.3.1.16. Graphs¶

4.3.1.16.1. The `type` parameter for graphs¶

4.3.1.17. Action¶

4.3.1. XML Tags¶

4.3.1.1. Solver¶

4.3.1.2. Tab¶

4.3.1.3. Model¶

4.3.1.4. Modelonoff¶

4.3.1.5. Param¶

4.3.1.5.1. Param “Entry”¶

4.3.1.5.2. Param “Browser”¶

4.3.1.5.3. Param “Cluster”¶

4.3.1.5.4. Param “Selection”¶

4.3.1.6. Info¶

4.3.1.7. Comment¶

4.3.1.8. Choice¶

4.3.1.9. Option¶

4.3.1.10. Multiple¶

4.3.1.11. Status¶

4.3.1.12. Xor¶

4.3.1.13. Desc¶

4.3.1.14. Docu¶

4.3.1.15. Include¶

4.3.1.16. Graphs¶

4.3.1.16.1. The type parameter for graphs¶

4.3.1.17. Action¶

4.3.1.16.1. The `type` parameter for graphs¶