CCP4i Documentation for Programmers: Core Documentation

Contents

Utilities for building CCP4i modules data structure (src/modules_utils.tcl)

Some utilities for constructing and interrogating the task and module references used for building the module and tasklist display. BuildModulesDataStruct takes the data previously read in from a modules.def file and populates an internal data structure by calling the "Set" and "New" commands (SetModuleProject, NewModule, NewModuleSeparator etc). The commands in browser_utils.tcl which actually build the display use the "Get" and "List" commands (ListFolderContents, GetTaskDesc etc) to acquire the information needed to make modules, folders and task buttons.

The internal data structure assigns a unique internal identifier to each task and folder at the point of generation. These unique identifiers are then used within the commands to access the data about the tasks and folders. Note that the identifiers may not be the same between different instances of the data structure.

BuildModulesDataStruct Build a data structure for the modules and tasklists

Argument list: <modulesVar> <arrayname>

The data in the modules.def file must previously have been loaded into the array specified by modulesVar (typically called moduledef).

Based on this data, this command constructs an internal data structure that can later be easily queried and modified by calling a set of interface functions.

modulesVar Name of the array containing previously loaded modules file

arrayname Name of array to store the data structure in

SortProgramList Sort the tasks in the program list module into alphabetical order

Argument list: <arrayname>

Intended to be called after an internal data structure has been built. Uses the compare_task_titles function to perform the comparision of two tasks in the sorting.

arrayname Name of array containing the data structure

compare_task_titles Internal - compare the titles of two tasks given their ids

Argument list: <arrayname> <taskid1> <taskid2>

Used by SortProgramList. Acquires titles of tasks given their ids and returns return of "string compare".

arrayname Name of array containing the data structure

taskid1 Unique id for first task

taskid2 Unique id for second task

SetModuleProject Set the project name and title within the data structure

Argument list: <arrayname> <project> <title>

arrayname Name of array containing the data structure

project Project name (usually 'CCP4')

title Title of application (usually 'CCP4 Program Interface')

arrayname Name of array containing the data structure

name Internal name of the module (e.g. 'datred')

description Description seen by the user (e.g. 'Data Reduction')

NewModuleSeparator Add a "separator" into the module list

Argument list: <arrayname>

arrayname Name of array to contain data structure

NewFolder Add a new folder to the data structure

Argument list: <arrayname> <name> <title> <desc> <module>

arrayname Name of array to contain data structure

name Internal name of the folder

title Text appearing on the folder title bar

desc Extended description used e.g. for tooltip help message

module Internal name of the module that holds the folder

NewTask Add a new task to the data structure

Argument list: <arrayname> <taskname> <title> <description> <module> <folder> <>

arrayname Name of array to contain data structure

taskname Internal name of the task (e.g. root of Tcl task file)

title Text to appear as task title on button

description Extended description used e.g. for tooltip help message

module Internal name of the module that the task is in

folder (optional) Internal name of the folder that the task is in

SetFolderVisibility Set the visibility of the folder contents

Argument list: <arrayname> <module> <folder> <status>

arrayname Name of array to contain data structure

module Internal name of the module that the task is in

folder Internal name of the folder

status Can be set to either OPEN or CLOSED

GetFolderVisibility Return the visibility of the folder contents

Argument list: <arrayname> <module> <folder>

Returns either OPEN or CLOSED, or UNKNOWN if the folder isn't found

arrayname Name of array to contain data structure

module Internal name of the module that the task is in

folder Internal name of the folder

ListModules List the modules in the data structure

Argument list: <arrayname>

arrayname Name of array to contain data structure

GetModuleDesc Return the description string for the module name

Argument list: <arrayname> <module>

arrayname Name of array to contain data structure

module Internal name of the module

ReverseLookupModuleName Given the module description, find the matching name

Argument list: <arrayname> <desc>

Attempts to locate the internal module name given the text description. Returns the name, or an empty string if no match is found.

arrayname Name of array to contain data structure

desc Description text to be matched

ListModuleContents Return a list of the module contents

Argument list: <arrayname> <module>

Returns a list of the unique internal ids for the tasks and folders in the module.

arrayname Name of array containing the data structure

module Internal module name

ListFolderContents Return a list of the module contents

Argument list: <arrayname> <module> <folder>

Returns a list of the unique internal ids for the tasks in the folder.

arrayname Name of array containing the data structure

module Internal module name

folder Internal folder name (unique id)

GetContentType Return the type (FOLDER or TASK) for the module content

Argument list: <arrayname> <module> <name>

arrayname Name of array to contain data structure

module Internal module name

name Task or folder name for which type is requested

GetFolderTitle Return the title string for a folder in a module

Argument list: <arrayname> <folderid>

arrayname Name of array containing the data structure

folderid Internal unique folder id

GetFolderDesc Return the description string for a folder in a module

Argument list: <arrayname> <folderid>

arrayname Name of array containing the data structure

folderid Internal unique folder id

GetTaskName Return the taskname for a task id

Argument list: <arrayname> <taskid>

arrayname Name of array to contain data structure

taskid Internal taskname (unique id)

GetTaskTitle Return the title string for a task

Argument list: <arrayname> <taskid>

arrayname Name of array to contain data structure

taskid Internal taskname (unique id)

GetTaskDesc Return the description string for a task

Argument list: <arrayname> <taskid>

arrayname Name of array to contain data structure

taskid Internal taskname (unique id)

Utilities for manipulating CCP4i modules.def files (src/modules_utils.tcl)

Some utilities for adding and removing task and module references.

InitialiseModulesArray Initialise an array with the data in a modules.def file

Argument list: <modules_file> <arrayname>

This is a wrapper for InitialiseArray which first loads parameters from the template modules.def file, to ensure that all expected parameters are initialised. It then loads the actual data from the file specified by the calling subprogram.

modules_file Full path for the module file to be loaded

arrayname Name of the array to store the data in

GetModuleList Return a list of the modules in the specified modules def file

Argument list: <modules_file>

This procedure returns a list of modules found in the modules.def file. Each element of the list is itself a list of two elements, the first being the internal name of the module, and the second being the module title as seen by the user. Note that this procedure can read information from either a .def style modules file, or from the old-style flat ascii format modules file.

module_file Full path for the module file to be examined

GetTaskList Return a list of the tasks in the specified module of a modules def file

Argument list: <modules_file> <module_name>

This procedure returns a list with each element representing a task in the specified module. Each element of the list is itself a list of three items, representing the task title (text seen on the task browser buttons), task name (corresponding to the task file), and the task description (text appearing in the task browser message line). Note that this procedure can read information from either a .def style modules file, or from the old-style flat ascii format modules file.

Note that if the module also contains folders then the names of the folders will also be returned in the list of "tasks". Therefore GetTaskList is now deprecated in favour of GetModuleContentList, which returns the same data with an additional flag indicating whether the entry is a task or a folder.

module_file Full path for the module file to be examined

module_name The name or title of the module to be examined

GetModuleContentList Return a list of the items (tasks and folders) in the specified module

Argument list: <modules_file> <module_name>

This procedure returns a list with each element representing a task or folder in the specified module. Each element of the list is itself a list of four items, representing the task/folder title (text seen on the task browser buttons or in the folder title bar), task or folder name (corresponding to the task file, or to the internal id name of the folder), the task or folder description (text appearing in the task browser message line), and the word TASK or FOLDER (indicating whether the item is a task or folder). Note that this procedure can read information from either a .def style modules file, or from the old-style flat ascii format modules file.

Note that only modules.def files can contain folders.

module_file Full path for the module file to be examined

module_name The name or title of the module to be examined

GetFolderContentList Return a list of the tasks in the specified folder of a module

Argument list: <modules_file> <module_name> <folder_name>

This procedure returns a list with each element representing a task in the specified folder and module. Each element of the list is itself a list of three items, representing the task title (text seen on the task browser buttons), task name (corresponding to the task file), and the task description (text appearing in the task browser message line). Note that this procedure can read information from either a .def style modules file, or from the old-style flat ascii format modules file.

Note that only modules.def files can contain folders.

module_file Full path for the module file to be examined

module_name The name or title of the module to be examined

folder_name The name or title of the folder to be examined

AddModule Add a new module reference to the specified modules def file

Argument list: <modules_file> <module_name> <module_title> <args>

Adds a new module reference to a modules def file, and overwrites with the new version. The new module will be empty when created, and by default is added to the end of the list of modules. Returns 1 on success, 0 on an error (e.g. modules file not found, module name or title already exists).

module_file Full path for the module file to be edited

module_name Name of the new module

module_title Title of the module (text which appears in the list of modules as seen by the user)

-before module_title

Add the new module before the named module, if possible

-after module_title

Add the new module after the named module, if possible

-first

Add as the first module

-last

Add as the last module

GetModule Fetch the attributes of a particular module reference

Argument list: <modules_file> <module>

Get the details of a module from a modules.def file, specifically the name and title.

On success this command returns a list of two elements: the module name, and the module title. On failure an empty list is returned.

modules_file Full path for the module file to be queried

module Name or title of the module reference to be queried

UpdateModule Change the module title text

Argument list: <modules_file> <module_name> <new_title>

module_files Full path for the module file to be edited

module_name Name of the module to be updated

new_title Text to be used as new module title

DeleteModule Remove a module reference from the specified modules def file

Argument list: <modules_file> <module_name>

Delete a module from the module def file. This will only work if there are no task references currently in the module.

module_files Full path for the module file to be edited

module_name Name of the module to be removed

AddTaskReference Add a new task reference to the specified modules file

Argument list: <modules_file> <task_title> <task_name> <task_descript> <module_name> <args>

Creates a new task reference in a particular module, and optionally within a subfolder.

Note that if a folder is specified but doesn't exist then the task reference will be added as a "top-level" task in the module. In all cases, if the module doesn't exist then the task reference will not be added at all.

module_file Full path for the modules file to be edited

task_title Title of the task (text which appears in the list of modules as seen by the user)

task_name Name of the task (must correspond to a .tcl file in the tasks directory)

task_descript Description of the task (text which appears in the message line of the main window)

module_name Module to which the task should be added

-folder folder_name

Add the new task reference within the named folder, if possible

-before task_title

Add the new task reference before the named task, if possible

-after task_title

Add the new task reference after the named task, if possible

-first

Add as the first task reference in the specified module

-last

Add as the last task reference in the specified module

AddModuleFolder Add a new folder to the specified modules file

Argument list: <modules_file> <folder_title> <folder_name> <folder_descript> <module_name> <args>

Creates a new folder reference in a particular module.

module_file Full path for the modules file to be edited

folder_title Title of the folder (text which appears in the list of modules as seen by the user)

folder_name Name of the folder (must be unique)

task_descript Description of the folder (text which appears in the message line of the main window)

module_name Module to which the folder should be added

-before task_or_folder

Add the new folder before the named task or folder, if possible

-after task_or_folder

Add the new folder after the named task or folder, if possible

-first

Add as the first entry in the specified module

-last

Add as the last entry in the specified module

GetFolderReference Fetch the attributes of a particular folder reference

Argument list: <modules_file> <folder> <module_name>

Get the details of a folder reference from a modules.def file, specifically the name, title and description.

On success this command returns a list of three elements: the folder name, the folder title and the folder description text. On failure an empty list is returned.

modules_file Full path for the module file to be queried

folder Name or title of the folder reference to be queried

module_name Name of the module in which the folder reference resides

UpdateFolderReference Update the attributes of a particular task reference

Argument list: <modules_file> <folder_title> <module_name> <args>

modules_file Full path for the module file to be edited

folder_title Name of the folder reference to be updated

module_name Name of the module in which the folder reference resides

-title title_text

New title text to replace the existing title

-descript descript_text

New description text to replace the existing description

DeleteModuleFolder Remove a folder from the specified modules def file

Argument list: <modules_file> <module_name> <folder_name>

Delete a folder from the specified module in a module def file. This will only work if there are no task references currently in the folder.

module_files Full path for the module file to be edited

module_name Name of the module to be removed

folder_name Name of the folder to be removed

UpdateTaskReference Update the attributes of a particular task reference

Argument list: <modules_file> <task_title> <module_name> <args>

modules_file Full path for the module file to be edited

task_title Name of the task reference to be updated

module_name Name of the module in which the task reference resides

-title title_text

New title text to replace the existing title

-descript descript_text

New description text to replace the existing description

-folder folder_name

Specify the folder that the task reference is currently in

DeleteTaskReference Remove a task reference from the specified modules def file

Argument list: <modules_file> <task_title> <module_name> <folder_title>

modules_file Full path for the module file to be edited

task_title Name of the task reference to be deleted

module_name Name of the module from which the task is to be removed

folder_title (Optional) Title of the folder within the module from which the task is to be removed