Tcl scripts can be loaded on top of the interface in order to provide extensions which add extra functionality. Extensions should be accessed by the user from the Extensions menu. Therefore Tcl scripts must add new commands to this menu, using the widget path .m.ext.e.
This process is best illustrated with a simple example. The script below adds a command to produce a genie-2 style plot of ISIS data.
set e .m.ext.e
$e add command -label "Genie-2 plot" -command e_display
proc e_display {} {
global g_current_set
gcl "display $g_current_set"
g_setLimits
}
Internal data structure
Data is stored in Sets, with up to 100 stored in memory at any one time. A set contains a complete copy of data, including all individual data elements stored as labelled entities called fields. An example of a field would be "plot title" or "X array". Sets can be selected, manipulated to create new sets, or graphically displayed. Every file read results in a new set being created. Sets can be reviewed or selected from "select set" on the SELECT menu.
Sets are represented internally by genie using a 101 element array of workspaces called wa. The last element being reserved as a temporary workspace, and the first 100 mapping to sets. The genie variable count keeps track of the number of workspaces used, and so can be used to find the position of the next available array element. In general set numbers map directly to wa indexes, but this may not always be the case, e.g. if a delete set option is implemented.
In general, for most applications the internal structure need not be considered. The global variable g_current_set and the procedure g_getSet hide these details. These should be used wherever possible to future proof any extension code. Two procedures are also provided for creating a new set, g_createSet and g_copySet. The later of which creates a new set from an existing set.
Useful Tcl global variables
 | g_current_set - the current set in genie notation, e.g. wa[3]. |
| g_current - the current Tcl set number, 0 indicates no data. |
| g_clear - Tcl clear between plots flag (1 = clear, 0 = don’t clear). |
| g_gd - Tcl graphics defaults array, see source code for details. |
| g_pd - Tcl program defaults array, see source code for details. |
| g_limits - Tcl limits array for current plot (xmin, xmax, ymin, ymax, dxmin). |
The set defaults array
The set defaults array contains useful setting for each set, such as which work space array element to use as an X array etc. The function g_getSet is provided to access this array.
The following fields are currently available:
| x (the X Array) |
| y (the Y Array) |
| e (the E Array) |
| t (the Plot Title) |
| xl (the X Axis Label) |
| yl (the Y Axis Label) |
These fields are defined for a set by its associated template.
Useful functions / procedures
Data manipulation procedures
| g_getSet {set} - returns name of genie workspace used by set, e.g. wa[3]. |
| g_getSet {field} - returns full workspace path of field for the current set, e.g. wa[3].x. |
| g_getSet {set field} - returns full workspace path of field for set. |
| g_setCount {} - returns the number of sets used. |
| g_createSet {}- returns the number of the next empty set, and allocates a workspace to it. |
| g_copySet {} - creates a new set, copies the current set into it, and allocates it the same template. Returns the number of the new set. |
| g_copySet {set} - creates a new set, copies set into the new set, and allocates it the same template. Returns the number of the new set. |
| g_registerSet {set} - makes set the current set and updates the status line. |
| g_setf {set f} - set the filename/comment of set to f. |
| g_setb {set b} - set the block number of set to b. |
| g_getf {set} - return the filename/comment of set. |
| g_getb {set} - return the block number of set. |
| g_setTemplate {set tname} - set the template of set to tname. |
| g_getTemplate {set} - return the template name of set. |
| g_setLimits {} - automatically sets the current plot limits, and device co-ordinate limits based on scaling information obtained from the current window. |
| g_setLimits {xmin xmax ymin ymax dxmin dxmax dymin dymax} - sets the current plot limits to xmin, xmax, ymin, and ymax. Also sets the device co-ordinate limits to dxmin, dxmax, dymin, and dymax. |
A template must be associated with a set before g_getSet is called with a field. The specified field must also be defined within the template. Use g_setTemplate to set or change the template, if necessary.
Graphics procedures
| g_deactivate {args} - greys out one or more widgets. |
| g_Mdeactivate {path args} - greys out one or more items on the menu path. |
| g_activate {args} - enable one or more widgets. |
| g_Mactivate {path args} - enable one or more items on the menu path. |
| g_winPosition {win} - positions a top level window widget, win, correctly. |
The HTML help system
| g_help {filename directory} - starts the HTML help system with filename using directory for all files. |
All HTML files needed must reside in the same directory. Images should be standard GIF files and also reside in this directory. The "contents" button attempts to load a file named index.htm which should exist in the given directory. The system conforms to version 2.0 of the HTML standard.
Provided templates
The following templates are currently included in the main template directory:
| ISIS RAW File (x, y, e, t, xl and yl defined) |
| Genie 2 Intermediate File (x, y, and e defined) |
| 2 Column ASCII (x and y defined) |
| 3 Column ASCII (x, y, and e defined) |
Naming conventions
All global variables and procedures used within the interface are prefixed with g_. To avoid conflicts extensions should not prefix new procedures or variables with g_.
A more useful example?
The script below logs the X array of the current set, storing the result in a new set.
set e .m.ext.e
$e add command -label "log x array" -command e_logX
proc e_logX {} {
# copy the current set
set s [g_copySet]
# log the array
gcl "[g_getSet $s x] = log([g_getSet $s x])"
# add a comment
g_setf $s "from log example"
# register the new set
g_registerSet $s
}
If the new set is mapped to workspace array element 2, and its inherited template defines the X array as .x, then the gcl expression above would evaluate to: wa[2].x = log(wa[2].x)
A slightly more complicated example
The following script creates a completely new set from scratch using the genie fill command.
set e .m.ext.e
$e add command -label "new set, created by fill" -command e_new
proc e_new {} {
# create a new set
set s [g_createSet]
# set template
g_setTemplate $s "2 Column ASCII"
# create the arrays
gcl "[g_getSet $s x] = dimensions(10)"
gcl "[g_getSet $s y] = dimensions(10)"
gcl "fill [g_getSet $s x] 1.0 1.0"
gcl "fill [g_getSet $s y] 1.0 2.0"
# add a comment
g_setf $s "fill example"
# register the new set
g_registerSet $s
}
If the new set is the first set created then the corresponding genie code produced would be:
wa[1].x = dimensions(10)
wa[1].y = dimensions(10)
fill wa[1].x 1.0 1.0
fill wa[1].y 1.0 2.0