Tcl callbacks

When certain events occur, VMD notifies the Tcl interpreter by setting certain Tcl variables to new values. You can use this feature to customize VMD, for instance, by causing new graphics to appear when the user picks an atom, or recalculating secondary structure on the fly.

To make these new feature happen at the right time, you need to write a script that takes a certain set of arguments, and register this script with the variable you are interested. Registering scripts is done with the built-in Tcl command trace; see http://www.tcl.tk/man/tcl8.4/TclCmd/trace.htm for documentation on how to use this command. The idea is that after you register your callback, when VMD changes the value of the variable, your script will immediately be called with the new value of the variable as arguments. Table 9.4 summarizes the callback variables available in VMD.

Table 9.4: Description of Tcl callback variables in VMD.

When called	Name	Description
Molecule molid was deleted	vmd_molecule(molid)	0
Molecule molid was created (data may not have been loaded yet)	vmd_molecule(molid)	1
Molecule molid was renamed	vmd_molecule(molid)	2
Structure file loaded	vmd_initialize_structure(molid)	1
Coordinate file loaded	vmd_trajectory_read(molid)	name of coordinate file
Molecule molid changed animation frames	vmd_frame(molid)	new animation frame
Any VMD command executed	vmd_logfile	Tcl text equivalent of command
An atom has been picked using the ''Pick" mouse mode	vmd_pick_event	When receiving this event, the following global variables are also set: vmd_pick_atom (id of picked atom), vmd_pick_mol (id of picked molecule)
Pointer moved.	vmd_pick_client	name of pointer
Pointer moved.	vmd_pick_mol_silent	id of nearby mol
Pointer moved.	vmd_pick_atom_silent	id of nearby atom
Atom picked	vmd_pick_shift_state	1 if shift key down during pick, 0 otherwise
IMD coordinate set received	vmd_timestep(molid)	frame containing new coordinates
Set of labels to be graphed	vmd_graph_label	{labeltype labelid} {labeltype labelid} ...
Tcl interpreter is shutting down	vmd_quit	1

In the VMD script library at http://www.ks.uiuc.edu/Research/vmd/script_library/, you can find a number of scripts that take advantage of Tcl variable tracing. Below, we give a simple example. The following procedure takes the picked atom and finds the molecular weight of residue it is on.

proc mol_weight {args} {
  # use the picked atom's index and molecule id
  global vmd_pick_atom vmd_pick_mol
  set sel [atomselect $vmd_pick_mol "same residue as index $vmd_pick_atom"]
  set mass 0
  foreach m [$sel get mass] {
    set mass [expr $mass + $m]
  }
  # get residue name and id
  set atom [atomselect $vmd_pick_mol "index $vmd_pick_atom"]
  lassign [$atom get {resname resid}] resname resid
  # print the result
  puts "Mass of $resname $resid = $mass"
}

Once an atom has been picked, run the command mol_weight to get output like:

Mass of ALA 7 : 67.047

Since VMD sets the vmd_pick_event, it can be traced. The trace function is registered as:

trace add variable ::vmd_pick_event write mol_weight

And now the residue masses will be printed automatically when an atom is picked. Make sure to turn off the trace when you are done with it (e.g. your plugin's window gets closed):

trace remove variable ::vmd_pick_event write mol_weight