	CCP4i: Graphical User Interface
	Documentation for Programmers
	The .def File

Files Required to Define a Task Window

The .def File Format

Data Types: Introduction; List of Data Types

File Types

MTZ Column Types

The types.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:

a .def file lists all the parameters controlled by the task window and specifies their data type and their initial value
a .tcl file is a Tcl script which defines the appearance of the task window

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 distibution 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 .def File Format

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:

you set the program version in the first line:
```
#CCP4I VERSION CCP4Interface 1.0
```
to the current program version as this may help sort out problems in version skews in the future
and the task name in the line:
```
#CCP4I SCRIPT DEF demo
```
to 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:

parameter name - one word, commonly in upper case
data type - one word, beginning with an underscore
initial value - must be enclosed in double quotes, and may be one word or a string, or empty

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).

Data Types

Introduction

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.

List of Data Types

_logical: Parameters of this type will be draw as a button and can have value 1 (true) or 0 (false).
_real, _positivereal, _negativereal: Parameters of this type will be drawn as an entry widget 6 characters wide. The data checking expects numerical input, with values greater than or equal to 0.0 for _positivereal, and values less than or equal to 0.0 for _negativereal.
_int, _positiveint, _negativeint: Parameters of this type will be drawn as an entry widget 6 characters wide. The data checking expects integer numerical input, with values greater or equal to 0 for _positiveint, and values less than or equal to 0 for _negativeint.
_fraction: Parameters of this type will be drawn as an entry widget 5 characters wide. The data checking expects numerical input with values greater than or equal to 0.0 and less than or equal to 1.0.
_text: Parameters of this type will be drawn as an entry widget 10 characters wide. Data checking will remove leading or trailing spaces, but will preserve other spaces.
_title_text: Parameters of this type will be drawn as an entry widget which is the maximum width for task titles.
_default_dirs: Parameters of this type are drawn as a menu which lists the user-defined project directories (these parameters are usually the first input field in any file input line and provide a mechanism for the user to move about the file system quickly).
_space_group: An entry widget is drawn. Data checking requires the input to correspond to the space group number code or name in the symop.lib file.
_angle: An entry widget is drawn. Data checking requires numerical input with values in the range -360.0 to 360.0.
_resolution: An entry widget is drawn. Data checking requires numerical input with value greater than 0.0.
_cell_length: An entry widget is drawn. Data checking requires numerical input with values in the range 0.0 to 9999.0.
_cell_angle: An entry widget is drawn. Data checking requires numerical input with values in the range 0.0 to 180.0.
_b_value: An entry widget is drawn. Data checking requires numerical input with values in the range -100 to 1000.
_sort_order: A menu is drawn listing all possible sort orders for HKL indices.
_xyz_sort_order: A menu is drawn listing all possible sort orders of XYZ.
_chain_id: An entry widget is drawn.
_res_id: An entry widget is drawn.

File Types

Look in the file for now - we need a table here!

MTZ Column Types

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.

_mtz_label_out: Parameters of this type will be drawn as an entry field for the user to enter a column name.

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 types.def File

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:

file
int
logical
real
mtz_label
menu
varmenu
list
datalist
default_dir

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 neccessary 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).