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.

Quick Overview¶

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.

Session

models opened/closed
selection changed
model position changed
begin/end session restore
ChimeraX quitting
new frame drawn

Atomic – creation/modification/deletion of atoms, bonds, residues, chains, and structures

Core – graphics background color change

UI – main window ready

Session Triggers¶

The triggerset is session.triggers. The most useful available trigger names are:

chimerax.core.models.ADD_MODELS: Models have been added to the session. The trigger data is a list of the models that were added.
chimerax.core.models.REMOVE_MODELS: Models have been removed from the session. The trigger data is a list of the models that were removed.
chimerax.core.selection.SELECTION_CHANGED: 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 session.selection.
chimerax.core.models.MODEL_POSITION_CHANGED: 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 None.
“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.UpdateLoop instance, which is rarely relevant.

Atomic Triggers¶

The atomic triggerset is obtained by calling chimerax.atomic.get_triggers(). 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 None. 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 chimerax.atomic.Changes instance, described below. 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.

Changes Methods¶

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 Collection. The methods are named created_X, modified_X, and num_deleted_X, where X is one of: atoms, bonds, residues, chains, pseudobonds, pseudobond_groups, coordsets, structures, or atomic_structures. Note that for efficiency reasons, for newly opened structures only the created_structures (or 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_reasons method, 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:

Class	Reason
Atom	alt_loc aniso_u bfactor color coord display draw_mode element hide idatm_type name occupancy selected serial_number structure_category
Bond Pseudobond	color display halfbond hide radius selected
Residue	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	chain_id residues sequence
PseudobondGroup	color halfbond radius
Coordset	coordset
Structure AtomicStructure	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).

Sessions¶

To get your attribute saved in sessions you will have to “register” it by calling atomic_class.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 keyword arguments:

attr_type: 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”).
can_return_none: True if None is a legal value. Defaults to False.

Changes Notifications¶

To get changes in attribute values reported in Changes objects, call session.change_tracker.add_modified(assigned, reason). assigned can be a single object, a Collection subclass, or an iterable of objects. reason is typically “attr_name changed”.

Core Triggers¶

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 chimerax.core.colors.Color, whose uint8x4() returns its RGBA value as an array of four (x4) 8-bit integers (uint8).

UI Triggers¶

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.