 |
CCP4i: Graphical User Interface |
| Documentation for Programmers | |
| Implementation |
|
File Organisation
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 |
General Utility Files
These are in the directory src.
- system.tcl
- contains system dependent procedures - these generally employ the Tcl exec function to invoke system commands. The file also contains some functions such as InitialliseArray which are needed to bootstrap the Interface.
- utils.tcl
- most of the utilities for the main Interface window, the task windows and for creating and running task scripts.
- CCP4_utils.tcl
- CCP4 specific utilities mostly for handling MTZ files.
- taskbrowser.tcl
- create and handle the main Interface window.
Defining Modules
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.
General Description of Task Interfaces
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:
- parameter name
- single word, upper case characters with underscores
- parameter type
- single word, beginning with underscore
- parameter value
- single word or phrase enclosed in quotes
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:
CreateTaskWindow window taskname arrayname {folder_titles}
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:
- window
- input a window identifier
- taskname
- used to identify files such as help files and script files
- arrayname
- the name of Tcl array associated with this interface
- folder titles
- title lines for the variable number of folders in the task window
CreateLine line message {arguments }
Create an interface line at the bottom of the current open frame:
- line
- return line id
- message
- a text message line which will appear when the mouse is over the line
then a variable number of parameters which take the form:
- label labeltext
- define text which will appear on the line
- widget parameter_name { arguments }
- define a widget for the parameter parameter_name. The nature of the widget will depend on the parameter type as defined in the taskname.def file.
- format format_mode {arguments}
- define the line format
Parameter Types
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.
Running Tasks
See Running a Job, part of the main Interface Documentation.