(updated August 2005)
On saving a file, it is often desirable to include in the file some sort of instructions to allow Mesquite, on re-reading the file, to bring the user as close as possible to the situation when the file was saved: what windows were open, what analyses were being done, and so on. This is accomplished (as well as can be) using Snapshots.
When the file is saved, a special MESQUITE block whose title is AUTO is saved in the NEXUS file. This block contains scripting instructions (see the page on scripting) to recover the state of analyses and so on. Its composition is coordinated by the getSnapshotCommands method of the Snapshot class, but the precise instructions are generated by the modules themselves.
When a file is saved, all modules are surveyed and requested to indicate what commands should be given to them to return them to their current state. A module returns this information via the getSnapshot method, which returns an object of class Snapshot. A Snapshot object includes a series of Strings each of which represents a command to the module. For example, suppose a module needs an employee module to calculate a number, and responds to a corresponding command to choose which module is so used, and the module also has a parameter named intervalWidth and a corresponding command setIntervalWidth to set it. The module might override the method getSnapshot as follows:
public Snapshot getSnapshot(MesquiteFile file) {Snapshot temp = new Snapshot(); temp.addLine("setIntervalWidth" + Integer.toString(intervalWidth)); temp.addLine("setNumberCalculator", numberTask); return temp; }
There are two versions of the addLine method of the Snapshot class. The first simply passes to the Snapshot a string to use as a command. In the example, the first addLine would cause the command
class
setIntervalWidth <number> ;
to be passed to the module. The second version takes two parameters: a string and reference to a MesquiteModule object. This version composes the command passed by appending the name of the module after the string, for example:
setNumberCalculator <name of module> ;
The reason the module reference is passed (instead of having the programmer do it by hand, as in temp.addLine("setNumberCalculator " + ParseUtil.tokenize(numberTask.getName()));) is so that the module composing the MESQUITE block knows the command refers to an employee to be hired. The script composed can therefore pass the instructions to this employee immediately upon its hiring. (The main reason to do this is that to avoid, in the resulting script, ambiguity in reference to employees with the same name. The command to hire the employee should return the employee hired (recall doCommand returns an Object) and the script can send the command to that very employee hired.)
Snapshots are also used to clone windows, and are presented at the user request if the user touches the "Snapshot" button in the information bar of a window.