next up previous contents index
Next: Python Text Interface Up: Text User 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 man/tcl8.0/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 8.3 summarizes the callback variables available in VMD.

Table 8.3: Description of Tcl callback variables in VMD.
When called Name New value
The molecule with id molid changed animtion frames vmd_frame(molid) new animation frame
New molecule created with id molid vmd_initialize_structure(molid) 1
Molecule with id molid deleted vmd_initialize_structure(molid) 0
Bond, angle or dihedral label added vmd_pick_value Value of geometry label
Atom picked vmd_pick_mol id of picked molecule
Atom picked vmd_pick_atom id of picked atom
Coordinate file loaded vmd_trajectory_read(molid) Name of coordinate file
IMD coordinate set received vmd_timestep(molid) frame containing new coordinates
Any VMD command executed vmd_logfile Tcl text equivalent of command

In the VMD script library at, you can find a number of scripts that take advantage of Tcl variable tracing. Below, we give a very simple example.

The following procedure takes the picked atom and finds the molecular weight of residue it is on.

proc mol_weight {} {
      # 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_atom and vmd_pick_mol variables, they can be traced.

proc mol_weight_trace_fctn {args} {
(This function is needed because the functions registered with trace take three arguments, but ``mol_weight'' only takes one.)

The trace function is registered as:

trace variable vmd_pick_atom w mol_weight_trace_fctn
And now the residue masses will be printed automatically when an atom is picked. To turn this off,
trace vdelete vmd_pick_atom w mol_weight_trace_fctn

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