|
CCP4i: Graphical User Interface |
| Documentation for Programmers | |
| The .def File |
|
Files Required to Define a Task Window
The files to define a task window are in the directory $CCP4I_top/tasks. Two files are required for each task. For a task called foo, the two files must be called foo.def and foo.tcl. The function of these files is:
There are simple examples of each in the distributed CCP4i code called demo.def and demo.tcl.
For the task to be accessible from the main window it must be specified in the $CCP4I_top/etc/modules file. In the standard CCP4i distribution there are two lines at the top of this file to give access to the demo task interface. These lines are usually commented out by a '#' character at the beginning of the lines. You can remove the '#' to make the demo task interface accessible.
A more detailed description of the format of the modules file can be found elsewhere.
The initialisation .def file found in the tasks directory has the same format as the files used to save user-defined parameters. The first few lines of a .def file are some identifiers:
#CCP4I VERSION CCP4Interface 1.0 #CCP4I SCRIPT DEF demo #CCP4I DATE 16/01/98 16:05:30 #CCP4I USER lizp
These identifiers are most useful in the .def files which save user parameters but also appear in the initialisation .def files for consistency. It is important that:
#CCP4I VERSION CCP4Interface 1.0to the current program version as this may help sort out problems in version skews in the future
#CCP4I SCRIPT DEF demoto the name of your task because when reading a .def file, the CCP4i program checks that the .def file is appropriate for the task it is setting up.
You might also want to set the appropriate date and time for when you created the file, and give your name.
The parameters are then defined with one parameter per line. There are three fields on each line:
Parameters usually correspond to the input parameters for the CCP4 program and so could have a name similar to or the same as the program parameter name. The data type should either correspond to a generic data type defined in the file $CCP4I_top/etc/types.def (see generic data types for a list of common types) or should be a task specific menu which is defined in the .tcl file through the DefineMenu command (see specific data types). It would be possible to add a new data type to the types.def file if necessary.
The data type is important because the type of widget drawn by the Interface is determined by the data type. For example, if you define a parameter as having data type _logical, it will automatically be drawn as a button which can only have the values 0 or 1 corresponding to 'true' and 'false'.
The data type also informs the Data Checking Facility of the sort of input that is expected for each parameter (see also below).
The data types are defined in $CCP4I_top/etc/types.def. This file is formatted such that when it is read by the CCP4i program, all of the data is loaded into an array called typedef. A more detailed description can be found below.
The data type of a parameter determines how it will be drawn on the interface (as button, entry field or menu).
Note that there is a default width for entry fields (i.e. a maximum number of characters that can be entered) but this can be over-ridden by the -width keyword of the CreateLine command.
The data type also informs the input checking within the CCP4i program. The input checking is currently limited but may be extended in future so it is advisable to implement sensible data types now. If the user enters a value which fails the data checking, the entry field is highlighted in a contrasting colour but there is no block on the user continuing to run a program.
There is one data type which is not defined in the types.def file . Most menus are specific to one task interface and so the specification of menus is usually done in the .tcl file using the DefineMenu command.
Look in the file for now - we need a table here!
It is important to give any parameters which define input MTZ columns the correct type, as the CCP4i program will automatically present the user with a list of the columns of the appropriate type in an input file. Where the user is required to give the name for a column in an output file, the parameter should have the type _mtz_label_out.
All other _mtz_label parameters will be drawn as a menu which lists the columns in the file of the appropriate type.
| label type | column type | contents |
|---|---|---|
| _mtz_label_h | H | reflection index h,k,l |
| _mtz_label_f | F | structure amplitude |
| _mtz_label_d | D | anomalous difference |
| _mtz_label_sig | Q, W | standard deviation and weight |
| _mtz_label_w | W, Q | weight and standard deviation |
| _mtz_label_dw | W, Q | deviation of anomalous differences |
| _mtz_label_phi | P | phase angle in degrees |
| _mtz_label_hl | A | phase probability coefficient (Hendrickson/Lattman) |
| _mtz_label_j | J | intensity |
| _mtz_label_y | Y | M/ISYM |
| _mtz_label_freer | I | FreeRflag |
| _mtz_label_r | R | any other real parameter |
| _mtz_label_i | I | any other integer parameter |
| _mtz_label | * | anything |
The data types are defined in $CCP4I_top/etc/types.def. This file is formatted such that when it is read by the CCP4i program, all of the data is loaded into an array called typedef.
At the top of this file a small number of type classes are defined - these are currently:
Associated with each class is a list of the properties that will be specified for each data type of that class. For example, the class file has the properties:
format ext description viewer viewercmd
In the main part of the file there is a statement for each data type of the form:
set typedef(_pdb_file) { file PDB ".pdb" "pdb coordinates file"
{ "List file" "View in RasMol" } {TextViewer RunRasMol} }
This is a definition for the _pdb_file type. The Tcl set command is used to set the _pdb_file element of the typedef array to a list of the file properties.
The first item of the property list is the word 'file' which is necessary to clarify that _pdb_file belongs to the file class and that the rest of the list will be file properties. So, for example, the second and third items on the file class list of properties are 'ext' (the default file extension) and 'description'. For the type _pdb_file, these properties have the values '.pdb' and 'pdb coordinates file.
Within the CCP4i program, the commands GetTypeInfo and GetViewerList can be used to access the information on data types stored in the typedef array (see Library of CCP4i Commands).