CCP4i: Graphical User Interface | |
Documentation for Programmers | |
Implementation |
The CCP4 Interface release area has the following subdirectories and contents:
bin | scripts to start CCP4i and other utilities |
loggraph | source code for loggraph utility |
mapslicer | source code for mapslicer utility |
sketch | source code for Monomer Sketcher utility |
templates | templates to generate program command scripts |
utils | utility source code |
src | general source code |
tasks | definition of each task interface |
scripts | template scripts to run each task |
icons | utility files such as icon bitmaps |
help | HTML help files |
test | some test data |
etc | other utilities, e.g. the setup script and .def files (which contain parameter definitions) |
The conventions for file extensions are:
tcl | source file in Tcl/Tk scripting language |
def | initialisation parameters for a Tcl array - interpreted by InitialliseArray procedure |
script | template script file which is basically Tcl but with some keywords which are interpreted by the CreateScript procedure |
run | an independent Tcl script to run tasks - requires the utility functions in system.tcl |
modules | defines the modules and their component tasks for the Interface - interpreted by ReadTaskList procedure |
These are in the directory src.
The taskbrowser.tcl script requires a .modules file which defines the modules and their component tasks. The default file is $CCP4I_top/etc/ccp4i.modules.
The parameters controlled by each task interface are stored in a Tcl array which is initialised with the parameter values in the file $CCP4I_top/tasks/taskname.def. The Save&Restore button on each task interface gives the user the option to save the parameters in a file which will have the same format as the taskname.def file. On each line of the file are three fields:
The parameter type is a cross reference to the file $CCP4I_top/etc/types.def which contains definitions of all recognised parameter types. Some parameter types are fairly generic (e.g. _logical) but others are specific to a given task interface (e.g. _imprfx_fortran_format is specific to the "Convert to MTZ" task interface).
The task interface is defined by the file $CCP4I_top/tasks/taskname.tcl. This file is Tcl script but uses generic procedures to define the interface and contains a minimum of raw Tcl. This file contains the definition of two procedures: taskname_run and taskname_review which are invoked immediately before and immediately after the task script is run (ideally these procedures should not be necessary but, for now, they are useful place markers and catch alls!).
The procedures used to create the task interface need to be thoroughly documented. But are not yet. The two most significant procedures are:
Initialise the task parameters by reading the taskname.def file, create the outline task window, and set up the handling of options such as Help or Run. The procedure arguments are:
Create an interface line at the bottom of the current open frame:
then a variable number of parameters which take the form:
Parameter types are defined in the file $CCP4I_top/etc/types.def. Each parameter type has a name which begins with an underscore, and an associated list of properties. The first element in the list of properties is the class of the parameter type.
Different types of data have different properties dependent on their class - there are currently seven classes: integer, real, logical, text, file, menu and mtz_label. All parameter types belong to one of these classes and have the list of properties associated with their class. The classes and their associated properties are defined at the top of the types.def file. Other classes could be added as necessary.
Some of the parameter types are generic (e.g. _logical) but others probably only apply to one parameter in one task interface (e.g. _imprfx_fortran_format). The class of the parameter type determines the sort of widget which will be drawn for the parameter in the user interface. Currently the mapping of class to widget type is:
integer | - | entry box |
real | - | entry box |
logical | - | checkbutton |
text | - | entry box |
file | - | entry box |
menu | - | pop-up menu |
mtz_label | - | pop-up menu or entry box |
The data checking applied to user input of parameters is determined by the parameter type information.
There is currently very little checking of user input (WG2 don't seem to think they want it!). I think that at least a minimal checking that the user has input something to the fields where data is required would be useful. In the current implementation some data is considered to be OBLIGATORY - the input field is in contrast colour until the user enters something reasonable but the job will still be run even if no data has been entered (it would be better called ADVISORY rather than OBLIGATORY!). There is currently a problem in that the OBLIGATORY/NOT OBLIGATORY property is a static but it should be variable. The best example of what is currently implemented is in the "Convert to MTZ" task interface if you select any file format other than the default MTZ.
It is not really necessary to make a final decision on how much data checking goes on as the parameter types are currently defined to support checking and it would require small change in one place to implement it. BUT to support the OBLIGATORY fields indication properly will probably need some additional code in all the individual task interfaces so it would save hassle to define what is required now.
See Running a Job, part of the main Interface Documentation.