Well Known Triggers¶
Bundles may wish to be able to react when various events occur, such as models being closed, or a structure chain being deleted. Bundles can arrange for relevant code to execute by registering with the “trigger” that is fired when such an event occurs. The mechanism for registering with a trigger is described in triggerset: Support for managing triggers and handlers. This document describes the names and locations of important triggers that a developer might want to register for.
Grouped by triggerset location, here are some of the important triggers provided in ChimeraX. Later sections provide detailed information about accessing the triggerset, exact trigger names, and their associated data.
model position changed
begin/end session restore
new frame drawn
Atomic – creation/modification/deletion of atoms, bonds, residues, chains, and structures
Core – graphics background color change
UI – main window ready
The triggerset is
session.triggers. The most useful available trigger names are:
Models have been added to the session. The trigger data is a list of the models that were added.
Models have been removed from the session. The trigger data is a list of the models that were removed.
The current selection has changed. The trigger data is
None. The selection state of various atomic data types can be fetched by functions in the chimerax.atomic module (e.g.
selected_residues(session)) or more generically via methods of
A model has changed position relative to other models in the scene. Rotations and translations of models typically change the position of the camera relative to the models and not the positions of the models themselves. However, things like Match Maker superposition of models will move a model relative to other models. This trigger fires when such a position change occurs. The trigger data is the model that changed position.
- “begin restore session” / “end restore session”
A session is about to be restored. A bundle may want to suspend some kinds of processing during a session restore or postpone some processing until after the restore completes and the entire session is in a consistent state. The trigger data is the session object (which is the same as the current main session).
- “app quit”
ChimeraX is about to quit. Tools could kill running subthreads or query about saving unsaved editing changes, for instance. The trigger data is
- “new frame” / “frame drawn”
A frame of the main graphics is about to be drawn / has been drawn. Most frequently used to avoid updating graphical user interfaces faster than the 3D graphics itself updates, which would be wasteful and could bog down the user interface. The trigger data is a
chimerax.core.updateloop.UpdateLoopinstance, which is rarely relevant.
The atomic triggerset is obtained by calling
The two important trigger names are “changes” and “changes done”.
“changes done” is used if a bundle wants other bundles to be able to react to a change
before continuing processing, and its trigger data is
The “changes” trigger encapulates all changes to C++-level atomic data
(and some Python-level changes, see Python-Level Atomic Attributes)
since the last firing of the “changes” trigger.
The trigger data is an
If you are only interested in changes to a particular structure,
each structure has a
triggers attribute with a “changes”
trigger that will deliver a
Changes instance containing only
changes to that structure.
A Changes object has methods for querying what atomic items of a particular type
have been created or modified, or how many such items have been deleted.
The created/modified methods return the appropriate type of
The methods are named
where X is one of:
Note that for efficiency reasons, for newly opened structures only the
created_atomic_structures) method holds any data, so if you care about items created by
new structures as well as those added to existing structures, you will have to check the
created_structures method and use the appropriate Collection property to get the items of interest.
For modified items you can also find out what changed by using the X
where X is the same list as before except using the singular form instead of plural.
These methods return a set of strings, each string of the form “item changed”.
Item is frequently an attribute name, but can be more generic.
For instance, changing one or more of the coordinates in a Coordset will produce a
“coordset changed” reason for Coordsets, which doesn’t correspond to any single attribute.
For each class, here are the changes that are tracked:
alt_loc aniso_u bfactor color coord display draw_mode element hide idatm_type name occupancy selected serial_number structure_category
color display halfbond hide radius selected
chain_id insertion_code name number ribbon_adjust ribbon_color ribbon_display ribbon_hide_backbone ring_color ring_display ring_mode ss_id ss_type
chain_id residues sequence
color halfbond radius
active_coordset ball_scale display ribbon_display ribbon_tether ribbon_orientation ribbon_mode scene_coord
Python-Level Atomic Attributes¶
ChimeraX has no way of knowing when Python-level attributes are defined or changed.
If you define a new attribute of one of the atomic classes, you will have to take
steps to get that attribute saved in sessions and to get changes to that attribute to
show up in
Changes objects (the latter only necessary if you think other bundles might want
to know about such changes).
To get your attribute saved in sessions you will have to “register” it by calling
.register_attr(session, attr_name, registrant) where “registrant”
is some string identifying the source of the registration (used in registration-conflict
error messages) – frequently your bundle name.
register_attr() has a few optional
If the attribute is always either a particular type (e.g. float) or
None, then specify this. This helps interfaces and commands that categorize attributes by type (e.g. “color byattr”).
Noneis a legal value. Defaults to
To get changes in attribute values reported in
Changes objects, call
assigned can be a single object, a
Collection subclass, or an iterable of objects.
reason is typically “attr_name changed”.
Settings objects each have a triggerset that fires a “setting changed” trigger
whenever a setting is changed. The associated data is a three-tuple of (setting name, old value,
new value). The core settings object (
chimerax.core.core_settings.settings) has one setting of
general interest: “background_color”, whose value is a
uint8x4() returns its RGBA value as an array of four (
x4) 8-bit integers (
Bundles may need to delay some operations (e.g. adding entries to ChimeraX’s main menus)
until the ChimeraX main window has fully initialized.
Such bundles should register code to execute in response to the
session.ui.triggers triggerset’s “ready” trigger.