Some of your Python scripts may wish to be informed when various events in VMD occur. The mechanism for expressing this interest is to register a callback function with a special module supplied by VMD. When the event of interest occurs, all registered will functions will be called; VMD will pass the functions information specific to the event. The set of callbacks events is listed in Table 9.4.
|Name||When called||Function arguments|
|frame||Molecule changes coordinate frame||(molid, frame)|
|help||User pushes help button on main form||(name of topic)|
|initialize_structure||Molecule created or deleted||(molid, 1 or 0)|
|pick_atom||Atom picked in graphics window||(molid, atomid, key_shift_state (1 if shift key down during pick, 0 otherwise) )|
|pick_value||Bond, angle, or dihedral label created||(value)|
|timestep||New IMD coordinate frame received||(molid, frame)|
|trajectory||Completion of coordinate file read/write||(molid, filename)|
All callback functions must take two arguments. The first argument will be an object given at the time the function is registered; VMD makes no use of this object, it simply saves it and passes it to the callback when the callback function is called. The second argument to the callback function will be a tuple containing 0 or more elements, depending on the type of callback. The type of information for each callback is listed in the third column of Table 9.4.
Callbacks are registered/deregistered using the add_callback/del_callback methods of the VMD.vmdcallbacks module. The syntax for these methods is:
def add_callback(name, func, userdata = None): def del_callback(name, func, userdata = None):name should be one of the callback names in Table 9.4. func is the function object. userdata is any object; if no object is supplied, None will be passed as the first argument to the callback function. To unregister a callback, use the same name, func, and userdata as were used when the callback was registered. The same function may be registered multiple times with different userdata objects.