tools: Manage running tool instances

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

Attributes

ADD_TOOL_INSTANCE : str
Name of trigger that is fired when a new tool registers with the state manager.
REMOVE_TOOL_INSTANCE : str
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:
session : instance of chimerax.core.session.Session

Session in which this tool instance was created.

bundle_info : a BundleInfo instance

The tool information used to create this tool.

id : int, optional

See attribute.

Attributes:
id : readonly int

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

display_name : str

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

SESSION_ENDURING : bool, class-level optional

If True, then tool survives across sessions.

SESSION_SAVE : bool, class-level optional

If True, then tool is not saved in sessions.

help : str

URL for tool’s help

delete()

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(b)

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

Parameters:
b : boolean

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

display_help()

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

classmethod restore_snapshot(session, data)

Experimental API . Create object using snapshot data.

session

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

take_snapshot(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(ti_list)

Experimental API . Register running tools with state manager.

Parameters:
ti_list : list of ToolInstance instances

List of newly created running tool instances.

autostart()

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

find_by_class(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:
cls : class object

Class object used to match tool instances.

find_by_id(tid)

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

Parameters:
tid : int

Unique per-session identifier for a registered tool.

list()

Experimental API . Return list of running tools.

Returns:
list

List of ToolInstance instances.

remove(ti_list)

Experimental API . Deregister running tools with state manager.

Parameters:
ti_list : list of ToolInstance instances

List of registered running tool instances.

reset_state(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:
session : instance of chimerax.core.session.Session

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

data : any

Data saved by state manager during take_snapshot.

start_tools(tool_names)

Experimental API . Start tools that are specified by name.

take_snapshot(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:
session : instance of chimerax.core.session.Session

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

phase : str

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

flags : int

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