next up previous contents index
Next: Python Text Interface Up: Tcl Text Interface Previous: sleep   Contents   Index

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 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, 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

next up previous contents index
Next: Python Text Interface Up: Tcl Text Interface Previous: sleep   Contents   Index