tools: Manage running tool instances

This module defines classes for running tools and their state manager.

Attributes

ADD_TOOL_INSTANCEstr

Name of trigger that is fired when a new tool registers with the state manager.

REMOVE_TOOL_INSTANCEstr

Name of trigger that is fired when a running tool deregisters with the state manager.

Notes

‘ToolInstance’ and ‘Tools’ instances are session-specific. The ‘Tools’ instance is a singleton per session and may be referenced as session.tools. All running tools may be found via session.tools.

The triggers are also session-specific. To add and remove ‘ToolInstance’ handlers, use session.trigger.add_handler and session.trigger.remove_handler.

class ToolInstance(session, tool_name)

Bases: State

Base class for instances of running tools.

Classes for running tools should inherit from ‘ToolInstance’ and override methods to implement tool-specific functionality. In particularly, methods from session.State should be defined so that saving and restoring of scenes and sessions work properly.

Parameters
sessioninstance of chimerax.core.session.Session

Session in which this tool instance was created.

bundle_infoa BundleInfo instance

The tool information used to create this tool.

idint, optional

See attribute.

Attributes
idreadonly int

id is a unique identifier among ToolInstance instances registered with the session state manager.

display_namestr

If a different name is desired (e.g. multi-instance tool) make sure to set the attribute before creating the first tool window.

SESSION_ENDURINGbool, class-level optional

If True, then tool survives across sessions.

SESSION_SAVEbool, class-level optional

If False, then tool is not saved in sessions.

helpstr

URL for tool’s help

delete(self)

Experimental API . Delete this tool instance.

This method should be overridden to clean up tool data structures. This base method should be called as the last step of tool deletion.

display(self, b)

Experimental API . Show or hide this tool instance in the user interface.

Parameters
bboolean

Boolean value for whether the tool should be shown or hidden.

display_help(self)

Experimental API . Show the help for this tool in the help viewer.

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

property session

Read-only property for session that contains this tool instance.

take_snapshot(self, session, flags)

Experimental API . Return snapshot of current state of instance.

The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.

class Tools(session, first=False)

Bases: StateManager

A per-session state manager for running tools.

‘Tools’ instances are per-session singletons that track running tool instances in the session, as well as managing saving and restoring tool states for scenes and sessions.

add(self, ti_list)

Experimental API . Register running tools with state manager.

Parameters
ti_listlist of ToolInstance instances

List of newly created running tool instances.

autostart(self)

Experimental API . Start tools that should start when applications starts up.

find_by_class(self, cls)

Experimental API . Return a list of tools of the given class.

All tool instances that match cls as defined by isinstance are returned.

Parameters
clsclass object

Class object used to match tool instances.

find_by_id(self, tid)

Experimental API . Return a tool instance with the matching identifier.

Parameters
tidint

Unique per-session identifier for a registered tool.

list(self)

Experimental API . Return list of running tools.

Returns
list

List of ToolInstance instances.

remove(self, ti_list)

Experimental API . Deregister running tools with state manager.

Parameters
ti_listlist of ToolInstance instances

List of registered running tool instances.

reset_state(self, session)

Experimental API . Reset state manager to default state.

Overrides chimerax.core.session.State default method to reset to default state. Since the default state has no running tools, all registered tool instances are deleted.

static restore_snapshot(session, data)

Experimental API . Restore state of running tools.

Overrides chimerax.core.session.State default method to restore state of all registered running tools.

Parameters
sessioninstance of chimerax.core.session.Session

Session for which state is being saved. Should match the session argument given to __init__.

dataany

Data saved by state manager during take_snapshot.

start_tools(self, tool_names)

Experimental API . Start tools that are specified by name.

take_snapshot(self, session, flags)

Experimental API . Save state of running tools.

Overrides chimerax.core.session.State default method to save state of all registered running tool instances.

Parameters
sessioninstance of chimerax.core.session.Session

Session for which state is being saved. Should match the session argument given to __init__.

phasestr

Take phase. See chimerax.core.session for more details.

flagsint

Flags indicating whether snapshot is being taken to save scene or session. See chimerax.core.session for more details.