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, titleother
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, titleother
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, titleother
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, typeother
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 characAscii
is a string without ” “integer
,double
andcomplex
are tested while typingfraction
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, typeother
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, typeother
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, titleother
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: valueother
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, titleother
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. Ifsubcolumn = 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, titleother
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, defaultother
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
andbnd_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, scriptother
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"/>