CCP4I Documentation for Programmers: Core Documentation

CCP4i Documentation for Programmers: Core Documentation

The Task Mode (src/task.tcl)

The Task Mode

In task mode only one task window is visible - this is run with the command 'ccp4i -t taskname' To run in this mode bin/ccp4i.tcl calls the task procedure in src/task.tcl which does the necessary initialisation and opens the task window.

task Initialisation to run CCP4i in task mode.

Argument list: None

The Taskbrowser (src/taskbrowser.tcl)

The Taskbrowser

The taskbrowser.tcl file contains procedures which are specific for running the ccp4i task browser (i.e. the usual way to run ccp4i). This file has a list of the other files which must be sourced and the procedure taskbrowser which is called from the startup bin/ccp4i.tcl

taskbrowser Initialise CCP4i to run the taskbrowser

Argument list: None

Utilities for CCP4i Main Window (src/browser_utils.tcl)

Some utilities for CCP4i run in 'browser' i.e. normal graphical mode.

update_module_menu Populate the menu of available modules

Argument list: <m> <arrayname>

update_module_menu This creates entries in a menu corresponding to the modules loaded in to a data structure. Any existing entries are first deleted from the menu.

Argument list: <m> <arrayname>

m Name of the widget with the menu

arrayname Name of the array with the data structure (usually called moduledef)

GetTaskFile Get the Tcl file associated with a task

Argument list: <taskname>

This command looks up the name of the Tcl file that is associated with a taskname, and returns the full path to the task file (or a blank string if no Tcl is found).

taskname The name of the task for which the task file is required

GetRunCmd Return the command for running a task

Argument list: <taskname> <title> <>

Given the name of a task, return the command that should be executed to launch that task. The procedure checks that the task has an associated Tcl file, and if this is not found goes on to check whether the task is actually a utility program.

If the taskname does reference either a valid task or a valid utility then this command returns an empty string.

taskname The name of the task to get the command for

title (Optional) A title to be used for utilities

ReadTaskList Read the etc/$OPSYS/modules and $USER/.CCP4/$OPSYS/modules files

Argument list: <arrayname> <filnam>

Load the list of modules and tasks into the moduledef array

Modules and tasks are first loaded from the main CCP4i modules file and additional modules and/tasks are then read from the user's personal modules file (if it exists) and are appended to those already loaded.

ASIDE (1): The user's .CCP4 area has subdirectories unix/windows where modules files are stored - in the main CCP4i area these directories are UNIX/WINDOWS.

ASIDE (2): There is currently an issue that the 'internal' name of a task which is used for task file names etc. is also the task name seen by the user in the job list. It would be better if the modules file had a separate definition of the 'user visible' task name.

filnam Name of the 'modules file

arrayname Name of array to contain data (usually moduledef)

UpdateModulesList Update the lists of modules and tasks

Argument list: <modulesname> <arrayname>

To be filled in by pjx

modulesname Name of the array initialise from the modules.def file

arrayname Name of array to contain data (usually moduledef)

CreateTaskBrowser Draw the main graphical window of ccp4i

Argument list: <input_project> <input_title> <window> <arrayname>

input_project Name of input project - used in window title

input_title Additional input title used in communication dialog box

window The Tk window id

arrayname The module/task array (usually called moduledef)

module_help Handle user clicking for help on the Module menu

Argument list: <arrayname>

Go to the help page for the currently open module

update_module Update task menu when user changes modules

Argument list: <selection> <arrayname>

selection New module

arrayname The module/task array (usually called moduledef)

open_module_folder Open a module folder by (re)packing it

Argument list: <arrayname> <module> <name> <frame> <container> <folder>

arrayname The module/task array (usually called moduledef)

module The current module holding the folder

name The name of the folder

frame The containing frame widget name

container The widget containing the title bar

folder The frame widget holding the list of tasks in the folder

close_module_folder Collapse a module folder by unpacking it

Argument list: <arrayname> <module> <name> <frame> <container> <folder>

arrayname The module/task array (usually called moduledef)

module The current module holding the folder

name The name of the folder

frame The containing frame widget name

container The widget containing the title bar

folder The frame widget holding the list of tasks in the folder

update_module_scroll Update the scrolling region of the tasklist

Argument list: <frame>

When the tasklist is redrawn e.g. after and reposition the view

frame The containing frame widget name

check_task_prereq Check for prerequisites for a task

Argument list: <taskname> <taskfile>

When building the task list, check each task file for a procedure called taskname_prereq, and if it is found then execute it. The procedure should return 1 if the task can be run and 0 if not.

The task interface author should code the necessary checks (for example, ensuring that required program executables are available on the user's path) into the taskname_prereq procedure.

taskname The name of the task

taskfile The full path of the task file for this interface

MailHandler Create mail window for interface

Argument list: None

For Unix systems, calls the MailtoDev procedure to produce the mailer window. On Windows, starts up a browser pointing to the CCP4 on-line help page (www.ccp4.ac.uk/reportaprob.html)