Creating Windows

These are general window drawing procedures. Some procedures which are specific to drawing task windows are in taskwindows.tcl and some procedures which will draw one simple utility window are defined in util_windows.tcl.

All of the 'standard' windows in CCP4i are created with some standard \procedures:

OpenWindow: creates the shell of a window

CreateFrame: called after OpenWindow to create the basic internal folder structure and (very important) to attach an array to the window

CreateTaskWindow: Does everything OpenWindow and CreateFrame do plus creating some standard action buttons and titled folders.

The array which is attached to the window contains elements which are associated with the various widgets on the window and contain the currently entered or selected values for the parameters. These elements of the \array correspond to the parameters found in the def file for a task window or which must be defined by the DefineVariable command for use with CreateFrame. There are also elements of the array which perform a control function for things like the message line, the toggleable folders etc.. The elements have names which begin with uppercase e.g. PARAM_FRAME_nn.

Many procedures require the name of the data array as an argument -almost always referred to as arrayname. Some routines (e.g. CreateLine) do not require the array name to be input but get it from a saved 'system' variable which has been set by CreateFrame or CreateTaskWindow. This system variable can only be reliably used while the window is being initially defined. Any command which might be issued at a later time (after the user might have opened another window and the system variable being changed) must explicitly input the array name.

Argument list: <w> <title> <icon_name> <args>

This will open a window with a message bar and Help button but without the folder structure or default action buttons of the task window opened byCreatetaskWindow. This procedure is useful for creating more customised graphics windows and is used mostly by the 'core' ccp4i.

The window does not absolutely need to have an associated data array but will need to have an array defined if it is to support the message line.

See also OpenGridWindow

w Name of toplevel window. If this window exists the procedure does nothing.

title Title to appear at top of window

icon_name Short title to appear if the window is iconised

-help help_file

Enter the name of a help file to be attached to the window help button

-target help_target

Set target in the help file to help_target

-message arrayname

Display an message line and use the standard elements of the array arrayname to contain the required message text.

-class class

Enter a class definition for the Tk toplevel command NOT USED

-nomessage REDUNDANT

-resizeable

The window will be resizable by the user

-parent arrayname

Arrayname is the data array for a 'parent' window. If the parent window is closed then its children will also be closed

Argument list: <arrayname> <w> <title> <icon_name> <args>

When the child frames are arranged using the grid geometry manager it seems to be necessary to use grid all the way through the window definition. This procedure is used for customised window such as the file browser and sketcher rather than being a proper API.

The window is automatically created with a message bar and buttons frame and two additional frames called $w.main and $w.utils

arrayname Name of data array

w Name of toplevel window. If this window exists the procedure does nothing.

title Title to appear at top of window

icon_name Short title to appear if the window is iconised

-help help_file

Enter the name of a help file to be attached to the window help button

-target help_target

Set target in the help file to help_target

-class class

Enter a class definition for the Tk toplevel command NOT USED

-menu

Create a pull-down menu frame

Argument list: <arrayname> <args>

arrayname Name of data array for the window

-window window

Set the window id (the Tk id) to override the default array(WINDOW)

-unset

Unset the whole of array

Argument list: <w> <arrayname> <args>

To support the folder structure there must definitely be a data array associated with the window to contain the control parameters for the folders. By default the window will have a vertical scroll bar.

w The window id (a Tk id)

arrayname The data array for the window

-noscroll

Do not create a scroll bar.

Argument list: None

This procedure calls update_main_scroll to set the final size of the scrollable frame and run_update_script which tidies up extending frames.

Argument list: <frame> <args>

update_folder Update visibility of folder dependent on protocol defined by OpenFolder

Argument list: <folder> <arrayname> <element> <args>

NB this procedure is called from the 'trace variable' function and has three redundant arguments appended to args

folder The folder id

arrayname The name of the task array

element The array element which controls the visibility of the folder

args The arguments input to OpenFolder and defined in:

Argument list: <frame> <arrayname> <mode>

frame The number of a folder or 'all'

arrayname Name of data array

mode Optional If mode=view then scroll task window so the opened folder is visible (but this may not be functional).

Argument list: <framein> <args>

CloseSubFrame Close a sub frame

Argument list: None

toggle_frame_display Set up a trace command for handler controlling visibility of a line or subframe

Argument list: <line> <element> <hitstate> <hitlist> <table_row> <-1>

line Tk id of the line or frame

element Array element controlling line/frame visibility

hitstate Visibility state ('open' or 'hide') if value of element matches any value in hitlist

hitlist Tcl list of possible values for the control parameter

Argument list: <line> <arrayname> <element> <hitlist> <hitstate> <args>

Called when user changed value of the control parameter

line Tk id of the line or frame

arrayname name of data array

element Array element controlling line/frame visibility

hitstate Visibility state ('open' or 'hide') if value of element matches any value in hitlist

hitlist Tcl list of possible values for the control parameter

Argument list: <table> <arrayname> <element> <hitlist> <hitstate> <\>

This proc is equivalent to update_frame_display but for rows in a table and is called when the variable is changed. The row is made invisible by setting the height to zero.

table Tk id of the table

arrayname name of data array

element Array element controlling line/frame visibility

hitstate Visibility state ('open' or 'hide') if value of element matches any value in hitlist

hitlist Tcl list of possible values for the control parameter

table_row The number of the row in the table (first row = 0)

height The normal height of the row when it is displayed

Argument list: <button> <element> <hitstate> <hitlist>

line Tk id of the line or frame

element Array element controlling line/frame visibility

hitstate Visibility state ('open' or 'hide') if value of element matches any value in hitlist

hitlist Tcl list of possible values for the control parameter

Argument list: <button> <arrayname> <element> <\>

Called when user changed value of the control parameter

button Tk id of the button

arrayname name of data array

element Array element controlling line/frame visibility

hitstate Visibility state ('open' or 'hide') if value of element matches any value in hitlist

hitlist Tcl list of possible values for the control parameter

Argument list: <w> <contents>

The mechanism for creating a scrolling frame is devious. This procedure will create the basic scrollable frame and scroll bar and will then create the required contents of the scrollable frame by evaluating the script which is passed into this procedure as a block of text. The script is actually evaluated in the variable context one level up by using the uplevel command.

This is a very important procedure used by all windows with scroll bars.

w The window id (a Tk id)

contents The text for a script to define the contents of the frame.

Argument list: <frame> <args>

The mechanism controlling scrolling needs to know the extent of the scrollable frame in the task window. This update is slow and is done only if the number of lines displayed in a task window has changed. If the system parameter block_scroll_update is set to 1 (true) then update_main_scroll does nothing. This blocking mechanism is used to prevent any unnecessary and time consuming update of the scrollable extent while the task window is initially being drawn.

frame The Tk frame id of any frame or widget within the task window.

Argument list: <arrayname>

The extra elements control the display of extending frames etc. in a task window. If a task window is deleted it is safer to delete these elements before possibly redrawing the task window again.

arrayname Name of task window array

The array has already been tied to an interface and is probably going to be tied to a new interface. Variables which have a trace on them are listed in TRACE_LIST. These traces must be deleted to avoid attempts to access widgets that no longer exist.

arrayname The name of an array

Argument list: <arrayname>

The array element UPDATE_SCRIPTS may contain the text for some commands that extending frames require to be run after the rest of the windows are defined.

arrayname The data array for the window

Argument list: <root>

Root name for an array

Help, Message Line and Wait Commands

SetProgramHelpFile Set the name of the help file for the current window

Argument list: <program_name>

Argument list: <help_file> <help_target>

help_file Name of html file to display

help_target Optional target within help file

Argument list: <arrayname> <w> <m>

This is a generic interface to setting the inline help display.

arrayname Name of task interface array

w The id of a widget within the task window

m The text message to be displayed

Argument list: <arrayname> <w> <m>

Help messages are displayed in the message line in each CCP4i window. Depending on the configuration the help message will also be displayed as "bubble help", with the text appearing next to the appropriate widget after a short time delay.

arrayname Name of task interface array

w The id of a widget within the task window

m The text message to be displayed

Argument list: <arrayname> <w>

This is the counterpart of the ShowHelp command, which displays the messages in the first place.

arrayname Name of task interface array

w The id of a widget within the task window

Argument list: None

Call this to set up the toplevel widget for bubble help.

The toplevel widget is created and then hidden - when required it is filled with the appropriate text and placed in the correct position before being remapped to the screen.

Argument list: <w>

This command is triggered when the cursor moves over the widget. After a delay the help message is displayed (unless cancelled e.g. by the cursor leaving the widget).

w The id of a widget within the task window

Argument list: <w>

Called from bubblehelp_pending after a suitable delay

w The id of a widget within the task window

Argument list: None

This command is triggered when the cursor moves out of a widget.

Argument list: <arrayname> <m> <args>

arrayname Name of task interface array

m The text message to be displayed

-block

Block any subsequent attempt to set the message until the -unblock option is used

-unblock

Unset any block on updating the message line

Argument list: <message>

TkBusy' Iteratively set the cursor for all child windows to a watch/arrow

Argument list: <w> <d>

This function should not be used directly - use TkBusy

w The id for a window

d If false (0) set cursor to watch, if true (1) then reset cursor to arrow

Argument list: <w> <d> <0>

A watch cursor is used to indicate that the process is busy.

w The id for a window

d Optional, default 0. If false (0) set cursor to watch, if true (1) then reset cursor to arrow

File Selection Widgets

CreateInputFileLine Draw a line to select an input file

Argument list: <linein> <message> <label>

CreateOutputFileLine Draw a line to select an output file

Argument list: <linein> <message> <label> <fileout> <fileout_dir> <args>

FileViewer0 Extracts file name from a data array and passes to FileViewer

Argument list: <arrayname> <fileVar>

When the file viewer functionality is part of a callback, attached to a button (eg the 'Browse' button), then it is necessary to extract the name of the file from data array at the time the command is issued.

arrayname The data array for the window

fileVar The element of the array containing the file name

Argument list: <openmode> <arrayname> <fileVar> <dirVar>

This uses the SelectFile procedure to provide the file selection dialog but also ensure that any selection on the file input line is passed to SelectFile and that the returned selection is put into the correct variable

openmode Should be 'open' for an input file or 'save' for an output file.#d_arg arrayname Name of task interface array

fileVar The name of the element in the array containing the file name

dirVar The name of the element in the array containing the directory alias

Argument list: <arrayname> <arrayindex>

This assumes that there is a text input widget for the directory path in a task interface and this procedure is called if the user clicks a 'Browse' button.

arrayname Name of task interface array

arrayindex Name of an element in the array which contains the directory name

Argument list: <arrayname> <fileVar> <mode> <dirVar> <args>

The user input of a file name is OK if an input file exists or an output file does not exist. For input files the procedure will attempt file name completion- e.g. adding an extension to a file name.

arrayname Name of task interface array

fileVar Name of an element in the array containing the file name

mode Should be 'open' for an input file or 'save' for an output file

dirVar Name of an element in the array containing the directory alias

-notoblig

Entering a file name is not obligatory so field will not have a contrast colour if it is left blank

-ext ext

Enter a file extension to use in file name completion

-title title

If attempted file name completion finds several files which are consistent with input then present user with list to select correct file. The title is used as a title for the selection dialog box.

Argument list: <path> <aliasVar>

The user might type in a full path name rather than use the project or aliases. It is easier for ccp4i to keep track of files if the project or alias \is used so test any input full path and convert to a project/alias if possible.

path Full path name for file

aliasVar Returned project/alias.

Argument list: <dirin>

Resolve ~ or environment variable specifications and return a full path.

dirin The input directory path to be expanded.

Argument list: <arrayname> <dir>

The procedure will handle input of ~ or environment variable

The widget for the directory input is updated with status colour depending on the validity of the user input.

arrayname Name of data array

dir Array element containing directory path

Argument list: <mode> <arrayname> <dir> <file>

mode REDUNDANT

arrayname Name of data array

dir Array element containing directory alias

file Array element containing file name

Argument list: <arrayname> <file>

arrayname Name of data array

file Array element containing file name

Argument list: <arrayname> <input_fileVar> <output_dir>

arrayname Name of data array

input_fileVar Name of array element containing the input file name

output_dir Name of array element containing output directory alias

output_file Name of array element containing output filename

output_ext An extension to the filename root (usually _taskname) note this is not the usually meaning of file extension

-in

The 'output' file is actually an input file - do file validation as for an input file.

Argument list: <linelist> <cmd>

It's tricky to know when the user has finished entering a file name and we don't want to bind commands (which may be slow) to events such as one keyboard stroke cos liable to be slow. Compromise is to bind commands to user hitting Return or Tab or releasing middle mouse (ie. pasting).

linelist A Tcl list of Create*putLine lines to have bound command

cmd Text script of command to be bound

Argument list: <paramtype> <arrayname> <format> <filename> <element>

This is called after user has selected an input file. The file can be MTZ, map or pdb format. The GetParamFromFile procedure is called to get the data from the file and this procedure puts the data into the array element and updates the validity status for the element.

paramtype The name of the type of data - corresponding to element in *_file_data array

arrayname Name of the task array

format The file format (MTZ/PDB/MAP)

filename The array element containing the input file name

element The name of the element to be assigned a value

Argument list: <format> <file> <param> <datain>

format The file format (MTZ/PDB/MAP)

file The full path input file name

param The name of the type of data - corresponding to element in *_file_data array

datain Output. The returned data value

The Generic Line Widget

CreateLine Draw a line in a window

Argument list: <linein> <args>

CreateCheckbutton Create a checkbutton

Argument list: <widget_name> <args>

This wraps the Tk checkbutton command and sets the colours appropriately depending on the platform and the Tcl/Tk version. It accepts any argument that is also acceptable to the checkbutton command.

The wrapper is necessary because the colour scheme for 8.4 and earlier is not compatible with that in 8.5.

widget_name The name of the checkbutton widget

Argument list: <name> <xpos>

PackByTemplate Apply the template defined by CreateLineTemplate to pack a line

Argument list: <line> <pack_template>

This procedure called by CreateLine for any line with command 'format template'. The procedure uses the Tk place command (rather than pack) to set the position of each widget on a line.

line The Tk id for the line

pack_template The name of the template to apply

Argument list: <selection> <arrayname> <param0> <args>

There is a 'problem' with Tk that when a user selects the item from a menu the data in the array element associated with the menubutton is not updated. The menubutton argument -textvariable might look like it will do the trick but there is an issue of which context the variable is defined in (i.e. in the context of a procedure or the global context).

selection The text of the selected menu item

arrayname Name of data array

param0 The name of the array element associated with the menubutton

Argument list: <field>

This procedure used to support variable menus and CreateLabin (which is a special case of a variable menu)

field The menubutton widget

Argument list: <arrayname> <var> <value>

arrayname Name of data array

var Name of array element associated with the variable label widget

value New value for variable label

Argument list: <arrayname> <arrayindex> <widget_name> <n1> <n2> <op>

The Tcl trace command is used to call this procedure whenever the associated variable is changed.

arrayname Name of data array

arrayindex Name of array element containing the variable text for the label

widget_name Name of the widget (Tk id) to be updated

n1,n2,op Additional arguments added by the trace command

Argument list: <field> <cmd>

The command will be issued when the user changes the selected menu item or hits Return key or moves focus out of the entry widget

This procedure needs to check the existing command string and append to it.

field The Tk id for the widget

cmd The command to be bound

Argument list: <arrayname> <line> <ientry>

Argument list: <arrayname> <mode>

arrayname Name of data array

mode User's input of 'continue' mode

Argument list: <arrayname> <toggleonvar>

Handles the -toggleon option in CreateLine

arrayname Name of data array

toggleonvar Name of element in array to be toggled on

Argument list: <arrayname> <arrayindex> <format> <oblig> <0>

Checking is not very strict - for numerical input the data type defines integer/real and possible range. This procedure will try to correct poor input and will set the widget to the warning colour if input is wrong.

arrayname Name of data array

arrayindex Name of element in array

format Optional data type for the array element

oblig Optional 1=some data input is obligatory

Argument list: <arrayname> <arrayindex> <status>

arrayname Name of data array

arrayindex Name of element in array containing variable

status validity of user input 1=valid 0=invalid

Other Complex Widgets

CreateButton Create an action button in the 'button' frame of a window created by 'CreateFrame'

Argument list: <w> <name> <text> <command> <args>

w The window id (a Tk id)

name The button name (appended to the Tk widget id)

text Text to appear on button

command The command to be bound to the button

-message message

help message to associate with button

-default

undocumented

Argument list: <textframeVar> <stuff> <args>

NOTE: This procedure needs an extra option to allow the user to edit the text. The text probably ought to be associated with an array element (i.e. treated like any other widget) but there is question of when to update the array parameter.

And then should be fully documented API

textframeVar Returned Tk text widget id

stuff Text to enter in the text widget

-scroll

Make widget vertically scrollable

-height height

Height of widget in number of text lines

-arguments arguments

Arguments to configure the text widget (i.e. valid Tk arguments)

Argument list: <w> <text> <args>

w Tk id of the text widget

text Text to append to widget

-init

Reinitialise the widget (i.e. delete any existing text)

Argument list: <w>

When triggered, the modalDialog binding deiconifies and raises the window in question. When combined with the "grab" command, this is used to ensure that a window doesn't get lost under other windows on the desktop - attempts to access functions in other windows (e.g. by clicking on buttons) will instead trigger the binding to bring the specified window to the fore.

w Window to add the modalDialog binding to

Argument list: <counterVar> <column_length>

When invoked this procedure increments the counter for the number of items in the current menu column, if this exceeds the number in column_length then the counter is reset and 1 is returned (indicating that the current item should appear at the head of a new column); otherwise 0 is returned (indicating that the item should appear underneath the previous item in the same column).

counterVar Name of a counting variable which must be set to zero in the calling procedure for each menu

column_length The maximum number of items which can appear in each column of the menu

Task Window Utilities (src/taskwindow.tcl)

Task Window Utilities (src/taskwindow.tcl)

Utitlities specific to drawing task windows. Complements the utilities in windows.tcl which are more generic

Argument list: <taskname> <args>

This procedure is called when the user clicks on a task in the modules and tasks menu. It is also called from other context when a task window is to be drawn.

This procedure initialises parameters from the tasks/taskname.def file \sources the taskname.tcl file and runs the foo_setup and foo_task_window procedures.

taskname The name of the task

-array arrayname

By default the task parameters are placed in an array called taskname_project. An alternative arrayname can be specified here.

-args argstring

The text string argstring appended as argument when calling the taskname_run procedure

-subsiduary subsiduary_taskname

Also open a subsidiary task window for subsiduary_taskname by calling RunTask

-def deffile

The default def file defining initial parameters is ccp4i/tasks/taskname.def and this file will always be read if it exists. The optional deffile will be read after this default df file.

-module module

By default the taskname.tcl file which defines the interface should be in ccp4i/tasks directory but if module is defined then it will be expected to be in ccp4i/module/ directory

Argument list: <arrayname>

A major time consumer when drawing a task window is updating the scrollable frame controlled by the right hand side scroll bar. Updating this is done by update_main_scroll which is blocked while the window is been defined by taskname_run but is called after taskname_run is finished. #d_desc This procedure also deiconifies (i.e. displays the window on the screen)

Argument list: <w> <arrayname> <taskname>

This is a wrapper to RunTask, which does some cleaning up of the original window prior to invoking RunTask.

Any parameters set in the array are preserved and will be displayed in the redrawn window.

arrayname Name of array containing parameters for task

w The window id for the task window

taskname The name of the task

Argument list: <arrayname> <title> <icon_name> <frame_list> <args>

The arrayname and window id set up in the procedure are 'remembered' and used by subsequent calls to procedures such as CreateLine and CreateLabin. This procedure creates the folders for the task window and the action buttons.

Create task window taking task name and window name from array(TASK) and array(WINDOW)

arrayname Name of array containing parameters for task

title Title for task window

icon_name Name to appear on iconised window

folder_list A list of titles for folders in task window.

-action_buttons actions

Enter a list of action buttons to appear at the bottom of the widow. Options are: quit, reset, save, interactive, run, exit

-default_button default_action

Specify default_action as the default action button

-title

REDUNDANT

mode

REDUNDANT

-help_file help_file

The default help file is the file for the curr

Argument list: <wbuttons> <taskname> <w> <arrayname>

Draw the default run button with option to 'Run Remote' etc.

wbuttons The Tk frame id for the 'buttons' frame

taskname The task name

w The window id for the task window

arrayname Name of array containing parameters for task

Argument list: <taskname> <w> <arrayname>

Give user option to delete current task defaults file or move it. The task project defaults are in the project directory CCP4_DATABASE/taskname.def

taskname The task name

w The window id for the task window

arrayname Name of array containing parameters for task

Argument list: <mode> <old_njobs>

mode May be 'list' or 'graphs' to display listing or log graphs.

old_njobs The number of jobs in the project database when the task is first created. Log files will only be displayed for jobs run subsequently.

Argument list: <arrayname>

arrayname The name of the task array

Argument list: <taskname> <arrayname> <field>

taskname The task name

arrayname Name of array containing parameters for task

field REDUNDANT

Argument list: <taskname> <arrayname> <args>

By default this procedure saves the defaults for the project in the file project_directory/CCP4_DATABASE/taskname.def. Alternatively the 'user' defaults are saved in \$HOME/.CCP4/tasks/taskname.def. For some specific context the defaults may be saved to a file named defined in the task array as array(TASK_INPUT_DEF_FILE).

taskname The task name

arrayname Name of array containing parameters for task

-input

Save to file specified in array(TASK_INPUT_DEF_FILE) parameter

-user

Save to the 'user' defaults file

Argument list: <arrayname> <taskname>

After destroying the window the UnsetArrayExtras procedure removes all parameters in the array which are set up to control the window. These will be redefined when the window is redrawn.

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

After reloading parameters there are often major changes in a window particularly in the number of extending frames and such like. It is easiest to redraw the window from scratch.

mode May be: JOB_NUMBER - prompt user for number of job from which parameters should be taken, USER_DEFINED - prompt user for def file name, CURRENT - reset from ccp4i default parameters, PROJECT - user parameters from the project default file.

taskname The task name

w The window id for the task window

arrayname Name of array containing parameters for task

Argument list: <w> <arrayname> <taskname> <args>

If a taskname_close procedure exists then invoke it. Close the window and exit the interface if running in task mode.

w The window id for the task window

arrayname Name of array containing parameters for task

taskname The task name

-noexit

Don't exit if running in stand alone mode

-nounsetarray

Don't unset the array

Argument list: <taskname> <arrayname>

Currently only used for mr_database.

arrayname Name of array containing parameters for task

taskname The task name

Argument list: None

This command can be called to place a lock on the interface to prevent it from exiting before an operation is finished.

Argument list: None

InterfaceIsLocked Check whether the interface is locked and prevented from exiting

Argument list: None

ConfirmExitInterface Prompt for user confirmation before exiting the interface

Argument list: <source> <>

This is a wrapper to ExitInterface which pops up a confirmation dialog before exiting, and allows the user to change their mind.

The source argument can be used to indicate which interface component has triggered the call to exit the interface, as this may affect whether or not the user should be prompted to confirm the exit operation. Currently only "*exit*" (e.g. "exitbutton") is recognised, and indicates that the "Exit" button from the main CCP4i window was used to trigger the exit process.

source (optional) A keyword indicating the source of the exit request.

Argument list: None

The system(TERMINATE) parameter is also reset so any procedure attached to the trace set by SaveOnProgramExit will be called.

Argument list: <lineVar> <element>

lineVar Return the Tk frame id for the line

element The name of the parameter holding the title text.

Argument list: <arrayname> <element>

arrayname Name of array containing parameters for task

element The name of the parameter holding the title text.

Argument list: <author_list> <args>

author_list A list of authors (NB should be Tcl list)

-link link_text link_target

A URL link to be added to credits line.

-label lab

Override the default text 'Program author'

Argument list: <linein> <args>

WriteImage accepts images as either files or as Tcl images (created using the Tcl image command). If using an image file then the command will try to determine the type (currently either bitmap or photo) from the filename extension. To over-ride this, use the -type option to explicitly set the type.

See the Tcl image command for more information on images.

linein Return the Tk frame id for the line

-file

File name specifying the image. Not required if using the -image option.

-type

Image type as recognised by the Tcl image command. Not required if using the -image option.

-image

Identifier of an image already created by the Tcl image command. Not required if using the -file option.

Argument list: <utilname> <run_command>

This procedure is called when the user clicks on a utility in the modules and tasks menu.

This command may ultimately be better placed elsewhere in the CCP4i source code, however it is loosely analogous to RunTask - which is why it appears here for now.

utilname The name of the utility as it appears on the launch button

run_command Command to be executed to start the utility

Extending and Toggle Frames (src/exframe.tcl)

Extending and Toggle Frames

Read the Programmers Guide in main CCP4i Documentation.

Argument list: <indexVar> <def_proc0> <message> <title> <\>

A toggle frame widget differs from an extending frame in that each 'row' of the widget has a title line, similar to a folder title line, which may be clicked on to toggle the visibility of the 'row'.

indexVar Name of array element which is the counter for the number of open toggle frames.

def_proc0 Name of procedure which defines the content of one 'row'

message The message line associated with the 'Add whatever' button

title Title line for each toggle frame

add_text Text to appear in the 'Add whatever' button

indexed_parameters A list of all of the parameters which are referenced in the def_proc0 procedure

-depend dependent_frame

The name of the defining procedure for another toggle frame or extending frame widget which is incremented and edited in sync with the 'master' widget.

-child child_frame

The name of the defining procedure for another toggle frame or extending frame widget which is nested within this 'master' widget.

-noadd

Do not draw the Edit menu button and increment button for this widget. \This implies that this widget is dependent on another 'master' widget.

-edit_proc edit_procedure

When the user increments or edits the rows in the widget call the procedure edit_procedure. This procedure should be defined in the taskname.tcl file.

-justify side

Set the justification of the subframes. 'Side' can be left, right or center. The default is center.

Argument list: <frame> <arrayname> <def_proc0> <counter> <c1>

frame Tk id for the toggle frame

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter The 'row' number for the top level of nesting if this is a nested toggle frame (is 0 for a top level toggle frame).

c1 The 'row' number for the toggle frame.

Argument list: <arrayname> <def_proc0> <c1> <title>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

c1 The 'row' number for the toggle frame

title New title for the toggle frame

Argument list: <arrayname> <def_proc> <counter>

The visibility is dependent on the (FRAME_TOGGLE_....) parameter which is controlled by the checkbutton on toggle frame title line.

arrayname Name of array

def_proc Name of procedure which defines the content of one 'row'

counter The 'row' number

indexVar Name of array element which is the counter for the number of open toggle frames.

def_proc0 Name of procedure which defines the content of one 'row'

message The message line associated with the 'Add whatever' button

add_text Text to appear in the 'Add whatever' button

indexed_parameters A list of all of the parameters which are referenced in the def_proc0 procedure

-depend dependent_frame

The name of the defining procedure for another extending frame widget which is incremented and edited in sync with the 'master' widget.

-child child_frame

The name of the defining procedure for another toggle frame or extending frame widget which is nested within this 'master' widget.

-noadd

Do not draw the Edit menu button and increment button for this widget. \This implies that this widget is dependent on another 'master' widget.

-edit_proc edit_procedure

When the user increments or edits the rows in the widget call the procedure edit_procedure. This procedure should be defined in the taskname.tcl file.

Argument list: <def_proc0> <counter> <arrayname> <increment>

This is called after the programmer has explicitly changed the data for an extending frame; for example after reading a file and loading default data. Note that the programmer is responsible for ensuring that the data is consistent - particularly that all parameters are set for every new line to be added. BUT the value of the index variable should NOT be updated.

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames: the frame number of the parent

arrayname The name of the array

increment The increment to the index variable (i.e. the number of lines to be added or deleted).

Argument list: <frame> <arrayname> <args>

This is used by CreateLine and other general widget drawing procedures.#d_arg frame Tk id of currently open frame

arrayname The name of the array

Argument list: <lineVar> <message> <c1> <command> <def_proc0> <counter> <\>

lineVar Return the Tk id for the line

message The message line to be associated with the increment button

indexVar The name of the element containing the number of toggle/extending frame created.

command The appropriate command to update i.e. update_extendingframe0 or update_toggleframe0

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

add_text The text which appears on the increment button

ifedit Logical value 0/1 which indicates if the 'Edit' menu should have { he} usual edit functions (or if =0, will just have 'Delete Last Line' option).

Argument list: <mode> <arrayname> <def_proc0> <counter>

The menu options and the message line are updated when the user deletes or copies rows within the toggle or extending frames.

mode The edit mode: quit/delete/copy

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

Argument list: <arrayname> <def_proc0> <counter> <c1> <args>

User has clicked right mouse in a widget in an extending frame. If they are in edit mode then $array(XF_EDIT_$def_proc) specifies the edit mode.

arrayname Name of data array

def_proc0 Procedure name and name for this frame

counter For child frames the frame number of the parent

c1 The number of the selected row

-parent parent_def_proc

For child frame the name of the procedure drawing the parent frame

-before

Insert before the selected row

Argument list: <arrayname> <def_proc0> <counter> <dframe>

In practice the graphical object corresponding to the highest number frame is deleted. The data is shuffled up to overwrite the data in the frame selected for deletion.

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

dframe The number of the frame to be deleted

Argument list: <arrayname> <def_proc0> <counter> <dframe>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

dframe The number of the frame to be deleted

Argument list: <arrayname> <def_proc0> <counter> <c1>

This procedure used to cleanup the child frames when the user has opted to delete the parent extending frame

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

c1 The number of rows in the child frame

Argument list: <arrayname> <def_proc0> <counter> <fromin> <toin>

arrayname Name of the data array

def_proc0 Name of procedure which defines the content of one 'row'

counter The id of the parent frame if this is a child frame

fromin The source row

toin The target row (If = 0 append the data to the end of the extending frame)

Argument list: <arrayname> <def_proc0> <from> <to>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

from Copy data from this parent frame

to Copy data to this parent frame

Argument list: <arrayname> <def_proc0> <counter> <c1In>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

c1in Optional parameter. If set is the number for the new frame to be draw. Other the new frame number is the current number of frames plus 1

Argument list: <arrayname> <def_proc0> <counter> <c1In>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter For child frames the frame number of the parent

c1in Optional parameter. If set is the number for the new frame to be draw. Other the new frame number is the current number of frames plus 1

Argument list: <arrayname> <def_proc0> <counter>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

Argument list: <f> <arrayname> <def_proc0> <counter> <c1>

arrayname Name of array

def_proc0 Name of procedure which defines the content of one 'row'

counter The frame number of the parent

c1 The frame number of the child extending frame

Argument list: <arrayname> <varlist> <values> <c1> <c2>

This is called when an extra frame is added to an extending frame to initialise all the array elements in that frame. If an array element

arrayname Name of data array

varlist List of the root names for the array elements

values List of values for the array elements. Can be an empty string.

c1 The first index for the elements

c2 Optional. The second index for the elements

Argument list: <arrayname> <varlist> <c1> <c2> <>

arrayname Name of data array

varlist List of elements in array

c1 The first index number

c2 The optional second index number

Using the BLT Table Widget

Using the BLT Table Widget

These functions require using bltwish rather than wish. They draw a table with edit menu button and increment button similar to extending frames but are more efficient at handling larger amounts of data. The data for the table must be in a separate array - see the description of CreateTable

Argument list: <arrayname> <table_id> <dataVar> <data_spec> <f> <args>

This widget is created very differently to the extending frames and toggle frames but (for a consistent interface) has similar edit menu button and increment button at the bottom of the table. The table is designed \to have column titles but each element of the table is an entry widget and additional labels are not supported.

See the table by the side of the Monomer Library Sketcher window or the Edit Restraints in PDB window for examples.

arrayname Name of array

table_id A unique identifying name for the table

dataVar Array containing the tabulated data displayed in the table The data array is a 2-dimensional array with element names {$column_name,$ir} where {$column_name} is the name of the column and {$ir} is the row number.

data_spec A specification of the table - a list with one list item for each column. Each list item is also a list with the items: 0 - name of data in the column 1 - column title 2 - data type if not represented as a simple entry widget 3 - width of entry widget (number of characters) 4 - default initial value 5 - message line describing the data in the column

f The Tk id of the frame in which to create the table

-scroll

Put the table inside a scrolling frame with a vertical scroll bar.

-noedit

Do not draw the edit menu button and increment button under the table

-nolabel

Do not draw column titles

-row row_procedure

Specify the procedure to draw one row of the table

Argument list: <t> <column_titles>

t The Tk frame id for the table

column_titles The list of column titles

Argument list: <arrayname> <table_id> <frame>

arrayname Name of array

table_id A unique identifying name for the table

frame The Tk frame id for the table buttons frame

Argument list: <arrayname> <table_id> <ir>

If the -row argument to CreateTable specified a procedure to draw a row then call that procedure with the arguments arrayname and ir (the row number). Otherwise draw a default format row using the information on data type and entry widget width provided as argument to CreateTable.

arrayname Name of array

table_id A unique identifying name for the table

ir The row number

Argument list: <arrayname> <table_id> <row> <mode>

arrayname Name of array

table_id A unique identifying name for the table

row Add new row after row number row. row = end => append to end of table row = query => query user

mode Optional. If mode is copy then initialise the new row with data determined by the row argument: row = query => query user row = {[list} copy_from_row copy_to_row\]

Argument list: <arrayname> <table_id> <ir>

arrayname Name of array

table_id A unique identifying name for the table

ir The number of the row to delete or ir = end => delete last row ir = query => query user

Argument list: <arrayname> <table_id>

arrayname Name of array

table_id A unique identifying name for the table

Argument list: <arrayname> <table_id>

arrayname Name of array

table_id A unique identifying name for the table

Argument list: <t>

t The Tk id for the table

Argument list: <f>

Must be called after adding or deleting a row.

f The id of the Tk frame containing the table

Variable Menus (src/varmenu.tcl)

Variable Menus

This is the mechanism to handle menus whose menuitems may change during the lifetime of the window. For example in the AMoRe interface there is a menu to select a TEST_SPACE_GROUP which is must be one of the alternative \in the same Laue group as the space group of the input data. The appropriate menu can only be set after the user has entered the input MTZ file which provides the input space group information. To implement this there are the following definitions in the amore.def file:

TEST_SPACE_GROUP _laue_space_group ""

LAUE_SPGP_LIST _list_of_text ""

LAUE_SPGP_ALIAS _list_of_text ""

The TEST_SPACE_GROUP will be the test space group which the user will select from a menu which is defined in amore_setup:

set typedef(_laue_space_group) { varmenu LAUE_SPGP_LIST LAUE_SPGP_ALIAS 8 }

Here the datatype _laue_space_group is defined as a variable menu which has the menuitems taken from the parameter LAUE_SPGP_LIST and the 'alias' of the menuitems taken from the parameter LAUE_SPGP_ALIAS. Both of these parameters have been defined in the amore.def and are initially empty. When the user selects an input MTZ file the procedure amore_set_test_space_group is called which finds the appropriate Laue space groups and loads them into the variables LAUE_SPGP_LIST and LAUE_ALIAS_LIST and then calls the procedure UpdateVariableMenu to update the variable.

In these handling procedures the datatype for the variable menu (e.g. LAUE_SPGP_LIST) in the above example) is referred to as the deflistVar.Note that is quite possible for there to be multiple widgets which have the same variable menu and a list of these is stored in array(DEPVARS_$deflistVar).

Argument list: <arrayname> <depvar>

array(DEPVARS_$deflistVar) is list of all variables which are attached to created widgets which have list of possible values $deflistVar.

arrayname The name of the task array

depvar The name of the variable which associated which the widget which is been created.

Argument list: <arrayname> <mode> <nn> <deflistVar> <input> <\>

The input parameters aliaslistVar and alias are optional and not required if an alias parameter has not been defined.

arrayname The name of the task array

mode Can be 'initialise', 'append' or 'replace'

n The number of the menu item to be replaced in 'replace' mode

deflistVar Element of array containing the list of menu item

input input value(s) for deflistVar

aliaslistVar Element of array containing the aliases for menu items

alias input value(s) for aliaslistVar

Argument list: <arrayname> <mode> <varmenu_element> <\>

This procedure is called by a trace mechanism if the user changes another text widget which defines an item on the variable menu.

arrayname The name of the task array

mode Expected to be replace

varmenu_element The number of the menu item to be replaced in 'replace' mode

varmenu_name Element of array containing the list of menu items

inputVar Element of array containing the new value for the replaced menu item

Argument list: <arrayname> <element> <menu_listVar> <input_command>

Because each variable could potentially be attached to more than one widget this procedure call update_menu0 which redraws each individual instance of the menu.

arrayname The name of the task array

element The array element which has a variable menu widget

menu_listVar Element of array containing the list of menu items

input_command An additional command associated with the menu

Argument list: <field> <arrayname> <element> <menu_list> <input_command>

field The widget name of the menu

arrayname The name of the task array

element The array element attached to the variable menu widget

menu_list The list of menu items

input_command Optional command to be bound to an menu selection