Gui It ! Manual

Introduction : Main Goals of Gui It !
Example : The most simple GUI.
Main Items : A quick tutorial to the configuration file.
Reference : The extensive reference of all elements and attributes of the configuration file.
License : License, and copyright stuff.

Introduction

Gui It ! is designed to build a quick and efficient GUI (Graphical User Interface) Front End to command line tools. It includes the most common operations with command line tools : All these functionnalities are customized in a simple xml configuration file. This document aims at mastering its powerful syntax.

Example

<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<gui version="2.0" display="My Custom GUI">
 <intro height="50" filename="toto.html" />
 <program id="Test">
   <intro>Simple introduction text.</intro>
  <command>xmldiff diff "{before}" "{after}" "{output}"</command>
  <arg id="before" type="file" mask="Fichiers XML (*.xml)|*.xml">test.xml</arg>
  <arg id="after" type="file" mask="Fichiers XML (*.xml)|*.xml">test.xml</arg>
  <arg id="out" type="dir">{after,'-out':append}</arg>
  <out id="result" open-with="notepad">{out}</out>
  <settings>
   <parameter id="display-input">no</parameter>
  </settings>
 </program>
 <tab display="Tests">
  ...
 </tab>
 <nested display="Nested" href="test\launcher.gui" />
 <tab display="About">
   <intro height="100000">Copyright...</intro>
 </tab>
 <settings>
   <parameter id="width">500</parameter>
   <parameter id="height">500</parameter>
    ...
   <string id="Process">Lance le traitement</string>
   <string id="Help">Aide</string>
   ...
   <func id="dir" lang="python">os.path.dirname('{1}')</func>
   <func id="append">{'{'{1}':dir}','{'{'{1}':file}','{2}','{'{1}':ext}'}':join}</func>
   ...
</settings>
</gui>

Main items

The basic structure of the configuration is :

Reference

Containers : Containers element.
Introduction / Help Texts : Put a simple introductory description.
Commands : Specify the command to be executed.
Arguments : Text fields, buttons, combo boxes and other controls.
Results Fields : Output fields.
Settings : Customize almost everything else there.

Note that for lisibility reasons, attributes have been prefixed by '@'. So @display will appear in the xml file as <element display="value" />.

Containers

Four components can contains commands :

Element program

The program element can have two attributes : The program element can contain these elements : intro, arg, out, command, help,settings.
A program element should not contain items with the same @id (otherwise, the duplicated items might be unpredictable).

Element tab

The tab element has the same attributes as program.
It can contain these elements : intro, program, tab, nested, and settings. Other elements will not be parsed.
If two program contains arguments with the same @id, the system will try to maintain the value of all elements with the same id equal. So you will not have to re-choose your file if you decide to switch to another tab using the same kind of arguments.

Element nested

The nested elementt has the same attributes as program, plus the attribute @href that specifies the location of the configuration file to include. This element cannot include other elements.

Element gui

This element has the same attributes and elements as program or tab, plus a @version attribute to specify the version of Gui It ! for which this configuration file was designed. This is not currently used, but it is a good idea to put it, for future versions.

The element gui should only be used for the root element of the configuration file. It will behave as program or tab depending of the number of tab, program and nested childs. Basically, if there is none of these elements, the gui will behave as a program element. Attirbutes and allowed nodes will be so identical to program. If there is one or more of these other containers, the gui element will behave as tab, and therefore will have the same attributes and elements allowed.

Introduction / Help Texts

Introduction Texts allow you to add some more fun titles, copyright notices, or a quick help. They are rendered by a HTML component, so you can use all your favorite tags, and images. It is highly recommended to set a fixed height with the @height attribute

Element intro

Not much more to say about it. You have the choice to : You can use the following attributes :

Element help

Help elements are usefull to link a more complete documentation as the one provided in the introductory text. It is displayed in a separate frame. You can display as much as Help buttons as you want, they will be organized as you specified in the setting buttons-align. You can choose to include the HTML text inline, or in a separate file, included by the @href attribute.

Commands

The command element contains the definition of what will be executed. You can have several command elements in the same program element. This is usefull when the arguments are the same, and the difference is very light. in this case, one button per command element will be displayed, in columns or in rows, as you choosed in settings (button-align).

Element command

This element can have the following attributes :

The command itself can be provided directly in the text of the command element, or in a sub-element commandline. The command is the concatenation of the command element and all commandline elements, so using more of one of those solutions can lead to strange things. For more information about command line syntax, see commandline.

Two more elements can be used in this context : commandpath and workingpath.

Element commandline

The commandline consists in a normal expression, which will be evaluated. You can (and should) use all the arguments you defined, with all functions. Note that if you use filenames, it is always a good idea to use them quoted. A typical example would be : <command>xmldiff diff {before:quoted} {after:quoted} {output:quoted}<command>. Here are used three arguments (before, after, output), in a quoted form. The executed command could be : xmldiff diff "before.xml" "after.xml" "output.xml". The executed command will appear in a tooltip on the command button.

Element commandpath

The element commandpath prepends the command with a path where the command is located. This is usefull when you have very long commandpath : this commandpath will not be present in the tooltip, and so you will be able to control the meaningfull string, without all these path stuff. If a relative path is given, it will be defined relative to the working path (see below). commandpath is a plain string, you cannot use expressions in it.

Element workingpath

The element workingpath is the path from which the command will be executed. If none is specified, the path of the current gui configuration file will be used. This is very usefull if your scripts output results in a fixed directory. workingpath is a plain string, you cannot use variables in it.

Arguments

All the arguments are defined with the element arg. All of them respect a common syntax, described in the "Element arg" paragraph, and extra functionnalities, depending on there @type, described in the dedicated paragraph.

Element arg

The basic structure of an argument is :
Element arg - Expression

An expression is basically composed of texts and variables.

Texts can contain any type of characters, except {}:,'". On the top level, only {} are unusable, and you can use quote and comma.

The complete syntax of a variable expression is {arg1, arg2,...,argn:function}. function is the function to use, and if none is provided, the expression evaluator will simply concatenate all the provided arguments. Arguments can be :

When a function is specified, the function is called with the specified arguments. The argument list will be passed to this function. See the func element documentation in the settings section.

Expressions are displayed in fields when the GUI is launched. Then they are evaluated each time a referenced variable is changed. You can change the value of an argument variable containing an expression, but it will be changed each time a variable used in its expression is changed, thus overriding your change.

Do not create infinite loops in expressions. Do not try to make too complicated expressions as it will mess up the user.

Element arg - Type text

The text type is the simplest argument possible. Its only parameter is noedit. If params="noedit" is present, the text field will not be editable. Rather not very usefull...

Element arg - Type file

The file type is basically a text type with a file picker. You can specify a filemask by using the attribute @mask. If none is provided, the setting fl_FileMask is used instead. In addition, the setting mask_AllFiles is always added (typically in order to have always All Files (*.*)|*.*). If you do not want that, you will have to set this settings to empty string.

The file picker is opened in the directory and with the filename of the current argument value. If the picker does not open properly, this is maybe due to a wrong value (typically if there is some {} characters). Empty the text field and click on the picker again.

Element arg - Type dir
Same thing, the dir type is a text argument with a directory picker. No special other attributes and params are used.
Element arg - Type check
This type display a checkbox. This should commonly used for options. It can have two expressions : one used when the checkbox is checked, and the other when not. Special items are :

Examples :
<arg type="check" id="Test">--test<arg> is the simplest form. It will evaluate to '--test' when checked, and nothing when unckeched.
<arg type="check" id="Test" default="checked" ><checked>--test {test_value}<checked><unchecked>--no-test<unchecked><arg> is the most complete form : it is checked by default, and contains two differents values when checked/unchecked. One of them use another variable argument.

Element arg - Type combo

The combo argument is probably the most complex argument, and fortunatly,... the less used. It displays a combo box with several items. Items can have a display string which differs from the expression string. You can also edit the combo box, and therefore the value used will be the one you provided. I strongly discourage this type of usage, as it is far from the spirit of Gui It !.

Specificities are : Basic example :
<arg id="action" type="combo" default="2">
 <value>diff</value>
 <value display="Execute provided file">execute {file}</value>
 <value display="Nothing" />
</arg>

Results Fields

The goal of results fields is to display files produced by the command. If no file is produced, this panel can be masked by the setting display-out. All results fields are read-only texts, and have a open-with button. By default, this opens notepad, but you can (and should) specify another one in the configuration file.

Element out

The element out has mainly one attribute :

Settings

The settings section can customize or add functionnalitied to Gui It !. You can use a settings element in all containers (gui, program, tab, ...). Settings will thus be overriden.

Gui It ! has a special behavior for settings, as it always try to load a file called settings.gui in the same directory as the gui binary, to load the default settings. It will only load the settings part of this file. You can define there your brillant functions, and use them everywhere.

Element settings

The settings element will apply to the current container and all its childs. It has basically three kind of items :
Element settings - subelement string
The following strings are currently used : This list is probably not up to date. Please see the provided settings.gui file or gui_settings.py for the complete list.
Element settings - subelement parameters
The following parameters are currently used : This list is probably not up to date. Please see the provided settings.gui file or gui_settings.py for the complete list.
Element settings - subelement func
You can define functions to be used in the variable evaluation structure {var1..:function_id}. You must specify the attribute @id with a unique value (refers to function_id). You have currently the choice between two implementation languages :

As you guessed, {n} are replaced by the n-th argument provided to the function. In {'toto',tata:concat}, in the concat function, {1} will be replaced by toto (and not 'toto'), and {2} by tha value of the argument tata.

Some sample functions are provided in the settings.gui file.

License

Gui It ! is release under the GPL license, as its predecessor GUI Launcher. This basically means that you can freely use it and distribute it at no cost, and even modify the provided source code, in the respect of the GPL license.

The latest version of Gui It ! is available on http://www.via.ecp.fr/~remi/soft/misc/guiit/guiit_en.php3