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.
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
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
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
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')
Argument list: <arrayname> arrayname Name of array to contain 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
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
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
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
Argument list: <arrayname> arrayname Name of array to contain data structure
Argument list: <arrayname> <module> arrayname Name of array to contain data structure
module Internal name of the module
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
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
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)
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
Argument list: <arrayname> <folderid> arrayname Name of array containing the data structure
folderid Internal unique folder id
Argument list: <arrayname> <folderid> arrayname Name of array containing the data structure
folderid Internal unique folder id
Argument list: <arrayname> <taskid> arrayname Name of array to contain data structure
taskid Internal taskname (unique id)
Argument list: <arrayname> <taskid> arrayname Name of array to contain data structure
taskid Internal taskname (unique id)
Argument list: <arrayname> <taskid> arrayname Name of array to contain data structure
taskid Internal taskname (unique id)
Some utilities for adding and removing task and module references.
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
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
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
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
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
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
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
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
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
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
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
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
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
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 removedBuildModulesDataStruct Build a data structure for the modules and tasklists
SortProgramList Sort the tasks in the program list module into alphabetical order
compare_task_titles Internal - compare the titles of two tasks given their ids
SetModuleProject Set the project name and title within the data structure
NewModuleSeparator Add a "separator" into the module list
NewFolder Add a new folder to the data structure
NewTask Add a new task to the data structure
SetFolderVisibility Set the visibility of the folder contents
GetFolderVisibility Return the visibility of the folder contents
ListModules List the modules in the data structure
GetModuleDesc Return the description string for the module name
ReverseLookupModuleName Given the module description, find the matching name
ListModuleContents Return a list of the module contents
ListFolderContents Return a list of the module contents
GetContentType Return the type (FOLDER or TASK) for the module content
GetFolderTitle Return the title string for a folder in a module
GetFolderDesc Return the description string for a folder in a module
GetTaskName Return the taskname for a task id
GetTaskTitle Return the title string for a task
GetTaskDesc Return the description string for a task
Utilities for manipulating CCP4i modules.def files (src/modules_utils.tcl)
InitialiseModulesArray Initialise an array with the data in a modules.def file
GetModuleList Return a list of the modules in the specified modules def file
GetTaskList Return a list of the tasks in the specified module of a modules def file
GetModuleContentList Return a list of the items (tasks and folders) in the specified module
GetFolderContentList Return a list of the tasks in the specified folder of a module
AddModule Add a new module reference to the specified modules def file
GetModule Fetch the attributes of a particular module reference
UpdateModule Change the module title text
DeleteModule Remove a module reference from the specified modules def file
AddTaskReference Add a new task reference to the specified modules file
AddModuleFolder Add a new folder to the specified modules file
GetFolderReference Fetch the attributes of a particular folder reference
UpdateFolderReference Update the attributes of a particular task reference
DeleteModuleFolder Remove a folder from the specified modules def file