Python callbacks

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 10.4.

Table 10.1: Description of callbacks available to Python scripts running in VMD.

Name	When called	Function arguments
display_update	Screen redraw	none
frame	Molecule changes coordinate frame	(molid, frame)
help	User pushes help button on Main window	(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 pressed, 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 10.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 10.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.