What is GUIB

The Guib is a utility library that facilitate the creation of graphical-user-interfaces (GUI) aimed at creating and manipulating input files for numerical simulation programs. The idea behind the Guib project is to construct a special meta-language with two purposes:

1. define the syntax of the input file of a given numerical program
2. provide simultaneously automatic construction of the GUI on the basis of this definition.

This is achieved by providing a definition file which defines the two entities (input syntax and GUI). In the following text the term input file stands for an input file of a given numerical program, while the term definition file is a file that describes the syntax of the input file.

  An example application

To clarify what this is all about, consider the following input for a particular numerical simulation program:

K_POINTS automatic 
8 8 8 
1 1 1

((:- This is a fraction of the input file for a given numerical simulation program for electronic structure claculations of crystalline structures, and requests the generation of the k-point mesh [first line of input] using an 8x8x8 uniform grid [second line of input] with the shift of the mesh in all three directions [third line of input]. -:))

Now we will describe how to create an appropriate GUI with the Guib software. The process is fairly simple, and all we need is a proper definition file. Since Guib library is written in Tcl (more precisely in [Incr Tcl]), the definition file uses the Tcl syntax. Technically speaking, a definition file is a Tcl script. Therefore a minimum bacis knowledge of the Tcl language can help appreciably to understand the Guib definition files.

An example of such a definition file (in Tcl syntax) is shown here:

module example1\#auto -title "An example GUI" -script { # 1st-line of input line ktype -name "K-point input" { keyword kpoints K_POINTS var kpoint_type { -label "K-Point input" -textvalue { "Automatic generation" "Gamma point only" } -value { automatic gamma } -widget radiobox } } # 2nd-line of input line kmesh -name "K-point mesh" { packwidgets left var nk1 -label "nk1:" -widget entry -validate posint -default 1 var nk2 -label "nk2:" -widget entry -validate posint -default 1 var nk3 -label "nk3:" -widget entry -validate posint -default 1 } # 3rd-line of input line kshift -name "K-point mesh shift" { packwidgets left var s1 -label "s1:" -widget entry -validate binary -default 1 var s2 -label "s2:" -widget entry -validate binary -default 1 var s3 -label "s3:" -widget entry -validate binary -default 1 } }

Lets say that we store this definition in file myGUI.def. Then by executing the command

• guib myGUI.def

the following GUI will pop up:

  Explanation of the above definition file

The definition file starts with the module keyword, which includes the whole definition. In the definition file four Guib keywords are used: line, keyword, var, and packwidgets. The line stands for the line of input, keyword describes the keyword in the input file, var is used to describe variables in the input file, while packwidgets only specifies how to pack the widgets in the GUI (equivalent to Tk's -side option of pack command). A syntax of Guib keywords is the following (an example for var keyword):

var ID -option value -option value ...
or
var ID { -option value -option value ... }

The ID is a unique ID and is also used as the name of a variable. In above definition file keywords are written in blue color, while IDs are green. Note that a given ID can only be defined once. This means that the following code is invalid:

var food -label "Food for breakfast:" -widget entry var food -label "Food for lunch:" -widget entry; # not OK !!!

However if one wants to insist that both variables should be named food then this should be done as follows:

var breakfast -variable food -label "Food for breakfast:" -widget entry var lunch -variable food -label "Food for lunch:" -widget entry; # OK !!!

Here both vars have different IDs, but names of both variables are the same. They were set by -variable option. Note that ID is used as the variable-name only when -variable option is not used.

Now we describe the definition for each three lines of above input-file. For this purpose a line keyword is used, and the definition specified inside the line body defines the content of a given line of input-file.

1. The first line of the above input-file example consists of K_POINTS keyword and a variable. The value of the variable can be either automatic or gamma. The corresponding Guib definition is specified by the keyword line (i.e. line ktype -name "K-point input" ...). The K_POINTS keyword is specified by keyword kpoints K_POINTS, and the variable by the var kpoint_type {...}. Although the value of the variable can be either automatic or gamma, more user readable strings were specified for the GUI (compare -textvalue and -value options). The option -widget requests the type of widget to be displayed in GUI for this variable.
    
2. The second line of input-file consists of three positive integer numbers that define the k-mesh (one number per dimension). The corresponding Guib definition is again specified by the keyword line (i.e. line kmesh -name "K-point mesh" ...). Inside the line-definition three var keywords are specified. The program (as well as the GUI) expects positive integer numbers, therefore the -validate posint option is specified. A similar Guib definition follows for the third line of input-file (see line kshift -name "K-point mesh shift" ...).

  Event driven mechanism

Guib also supports an event-driven mechanism, and special keywords are provided for this purpose. A typical use of this is the situation where, on setting a particular value of a given variable, the program expects one type of proceeding input, while for another value of the variable the input is of another type. In the previous example, on selecting the "Gamma point only" option, one does not need to input the parameters for the automatic k-mesh generation. Hence, by the event-driven mechanism Guib can enable certain widgets and disable others.

In our case on selecting the "Gamma point only" option the lines "K-point mesh" and "K-point mesh shift" should be disabled (and enabled upon selection of "Automatic generation" option). Below is the corresponding part of the script that does the job, and here you can find the complete definition file myGUI.def (i.e. definition-of-input + event-driven-machanism).

# some advanced features: trace selection of # kpoint_type variable and enable/disable kmesh # and kshift widgets. tracevar kpoint_type w { set value [vartextvalue kpoint_type] if { $value == "Automatic generation" } { set status enable } else { set status disable } groupwidget kmesh $status groupwidget kshift $status }

The event-driven mechanism works by setting the traces on given variables using the tracevar keyword. The usage of the keyword is the following:

tracevar ID op script

The tracevar arranges for script to be executed whenever a given variable with id ID is accessed in one of the ways given by op. The ID can be an id of any variable defined by var, dimension or table.

Op indicates which operations are of interest, and consists of one or more of the following letters:

r

Invoke script whenever the variable is read.

w

Invoke script whenever the variable is written.

Keyword vartextvalue is used to query the textvalue (as specified by -textvalue option) of the variable (in our case the kpoint_type variable). Similarly the varvalue would be used to query the value (as specified by -value option) of the variable. The keyword groupwidget is used to manipulate the state of a group of widgets. The usage of the keyword is the following:

groupwidget groupID state

The groupID is the name of the group of widgets. In our case the groupID is the ID of a given line. Hence in above example we have three groups of widgets: (i) ktype, (ii) kmesh, and (iii) kshift. The state specifies the state of the widget to be set and can be either enable or disable.