General Utility Windows

These are a collection of 'super-widgets' to display stuff like warning messages and for some simple user input. Most of these widgets block input to all other ccp4i windows until the user has closed this widget. Programmers should be careful when using these that they do not create two blocking windows simultaneously - it usually freezes the interface. The WarningMessage function does test if a warning message window is already open and appends to it if possible.

The Tcl 'grab' command is used to grab the input focus for the window. The use of this command does seem to cause occasional error messages when running ccp4i - but the interface usually seems to continue without problems. Once the window has grabed the focus then the Tcl code is blocked by a vwait command - ccp4i will not process the user input until the user clicks an option to close the window. The 'close' command will call a procedure such as warning_message_command which releases the 'grab' and sets the vwait parameter (e.g. warning_message_flag) which allows the main procedure (eg. WarningMessage) to continue and exit.

Argument list: <message> <args>

message Text string to be displayed.

-help help_file

Link a help button in the warning message window to this html file.

-title title

A title for the warning message window

-nostop

Do not block the procedure waiting for user input - this is probably not a good idea

-transient delay

If there is no user input close the window after a given delay (delay in seconds)

-button button_text

Set the text of the 'Dismiss' button to button_text

-command command

When the user clicks the 'Dismiss' button then issue the command

Argument list: <arrayname> <returntext>

arrayname Name of data array

returntext The command from the action button

Argument list: <title> <icon> <message> <options> <args>

The window contains a message text and any number of buttons (4 is probably the reasonable maximum) - clicking a button will make the user's choice and close the dialog box. The text from the button clicked by the user is returned by the procedure.

The items in the input list of options are displayed right to left.

title Title for the window

icon Name for the window icon

message Text message to appear in the window

options A list of the text strings to appear in the buttons.

help help_file

Link a help button in the warning message window to this html file.

parent parent_window_array

The arrayname of the parent task interface. If that task interface window is closed by the user then this window will also be closed automatically.

-default n

Set the n'th item in the list of options as the default

mode mode

button or listbox (default button) The options can be listed in a listbox (not certain this is functional)

-height height

Height of listbox (number of lines)

-width width

Width of listbox (number of characters)

Argument list: <arrayname> <returntext>

arrayname Name of data array

returntext The command from the action button

Argument list: <arrayname> <lb> <y>

arrayname Name of data array

lb Tk id of listbox widget

y Position of mouse pick in listbox

Argument list: <title> <icon> <arrayname> <entry_list> <args>

The dialog box is laid out with one variable per line. Each line has a label to define the parameter and a input widget for the user to enter a value or edit the default value. The input default parameters should be defined in a global array (usually this will be a task interface array) and the output values are returned in the array.

The user has the options to exit the dialog box with 'OK' (the procedure returns 1) or 'Quit' (the procedure returns 0 and returns the variables in the array are unaltered).

title Title for the window

icon Name for the window icon

arrayname Name of array containing the input/output parameter values

entry_list A list with one item for each variable - each item is a list: the name of the lement in the array, the text to appear in the label, the parameter type (optional, default is _text).

Argument list: <comlineVar> <file>

This procedure is run as part of the ccp4i graphical main process if this process receive a request from a run process which is runnning a script. The command line is passed to (and returned from) this procedure explicitly but the command script is in a file which is read and then overwritten by the updated script if the user edits the script.

comlineVar Input/Output The text of the program command line

file Name of the file containing the file script

Argument list: <mode>

The EditComFile script will continue from the vwait command after edit_com_file_status is changed.

mode The action mode - dependent on which button was clecked

The same interface to either Uniqueify of Harvesting appear in several task windows so they are defined in the following procedures. For examples see scalepack2mtz (Uniqueify and HKL rejects) and truncate (harvesting). The def file and com files for the task also need to be modified, for example, for harvesting:

The taskname.def file for the task should contain the line

@ [FileJoin [GetEnvPath CCP4I_TOP] tasks harvest.def]

to initialise parameters defined in harvest.def. And the taskname.com file should contain

AT { [FileJoin [GetEnvPath CCP4I_TOP] templates harvest.com ] }

which will interpret the parameters into the program script.

Argument list: <arrayname>

See scalepack2mtz for example of use

arrayname Name of task interface array

Argument list: None

See scalepack2mtz for example of use

Argument list: <arrayname> <filename> <mode>

This is called at the beginning of **_task_window procedure (with mode=init) to initialise the harvest mode and PNAME if they are not already setor in the **_run procedure (with mode=run) to check the user entered values are consistent with MTZ contents.

arrayname Name of data array

filename Name of array element containing file name

mode Mode, valid values init or run

Argument list: <lineVar> <args>

lineVar Returned. The Tk line id for the final line.

-noha

do not draw the harvesting mode line

-dnam

always draw the pname/dname line (eg scalepack2mtz)

Argument list: <arrayname> <filename>

This command should be added as an argument to CreateInputFile command for the input MTZ file in form:

-command "UpdateHarvestMTZ $arrayname HKLIN"

arrayname Name of data array

filename array element containing the name of the MTZ file

Argument list: <arrayname> <i>

arrayname Name of task interface array

i Counter for entending frame

File Selection Window (src/fileselect.tcl)

File Selection Window

The procedures in fileselect.tcl control the display of the file selection window. The window can be significantly customised by the application programmer.

File types, extensions and viewers are defined in etc/types.def

Argument list: <fileoutVar> <args>

fileselectDefdir Update file list when user changes the default directory alias

Argument list: <defdir> <dir>

defdir The array element for the default directory alias

dir The array element for the file name

Argument list: None

fileselectViewers Set up the menu to allow user to select a viewer for a given file type.

Argument list: None

fileselectList Update list of directories and files visible to user

Argument list: <dir> <input_files>

dir The currently seelcted directory

input_files (Optional). Predefined list of files to be displayed.

Argument list: <args>

User has slected a file or directory from the lists, or has hit return in the text input widget or has clicked OK button. This procedure checks the input is sensible and updates text input widget, file and directory lists. If the input is appropriate then fileselect(DONE) is set to true (1). This variable is being 'watched' by a tkwait command and when it changes control returns to the SelectFile procedure which closes the file selection window.

-finish

Exit the file selection window if the input is OK.

Argument list: None

Sets the fileselect(DONE) variable which causes control ot pass to FileSelect procedure and to close file selection window.

Argument list: <lb> <y>

lb listbox id

y Y position of click in listbox

Argument list: <lb> <y>

lb listbox id

y Y position of click in listbox

Argument list: <lb>

lb listbox id

Argument list: None

up_directory Handle user selection of the 'go up a directory' widget

Argument list: None

sort_files Sort list of files by criteria of date or name

Argument list: <mode> <filelist>

Return a sorted list of files - just the filename without the path

mode The sort mode: date or name

filelist List of files, must be full path name of the files

Argument list: <a> <b>

display_file_list Put list of files into display listbox

Argument list: <w> <mode> <file_list>

w Listbox widget id

mode List mode: name or details

file_list List of files

Projects and Directories Interface (src/directories.tcl)

Projects and Directories Interface

This is the interface which is found under the 'Projects and Directories' button.

The window maintains a variable menu called PROJECT_MENU which is a list of the currently defined projects from which the user can select the current project.

The complications with this window comes mostly from the requirement to keep up to date the current project database and the menus listing the defined projects and aliases which appear on every file selection line. These are not updated until the user exits the window.

Argument list: None

This will be used for user command 'ccp4i -d'

Argument list: <arrayname> <param> <counter>

Also ensure that it does not contain unallowed characters

arrayname Name of the data array (probably 'directories')

param Name of the prameter to check (probably PROJECT or ALIAS)

counter The counter for the parameter

Argument list: <arrayname> <counter>

Part of the CreateExtendingFrame mechanism

arrayname Name of the data array (probably 'directories')

counter Counter for number of directories

Argument list: <arrayname> <counter>

Part of the CreateExtendingFrame mechanism

arrayname Name of the data array (probably 'directories')

counter Counter for number of projects

Argument list: <arrayname> <counter>

Procedure found automatically by the extending frames edit

arrayname Name of the task array

counter The updated number of projects

Argument list: <mode> <edit>

The initialisation stuff should probably be part of an autoconf procedure rather than here

mode Default is edit, or init mode which will set some initial defaults.

Argument list: <mode> <arrayname> <w>

Invokes DbChangeFile which updates the project database if necessary and update_defdir_menu which updates the directory alias menu which appears in all file selection lines.

Argument list: <arrayname> <var>

And remove disallod characters

arrayname Name of the data array (probably 'directories')

var Name of the array element containing the alias