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 labeled 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 = dont 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:
These fields are defined for a set by its associated template.
Useful functions / procedures
Data manipulation procedures
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
Provided templates
The following templates are currently included in the main template directory:
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