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: chimerax.core.state.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()

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)

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

Show the help for this tool in the help viewer.

session

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

class Tools(session, first=False)

Bases: chimerax.core.state.State

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)

Register running tools with state manager.

Parameters:

ti_list : list of ToolInstance instances

List of newly created running tool instances.

autostart()

Start tools that should start when applications starts up.

find_by_class(cls)

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)

Return a tool instance with the matching identifier.

Parameters:

tid : int

Unique per-session identifier for a registered tool.

list()

Return list of running tools.

Returns:

list

List of ToolInstance instances.

remove(ti_list)

Deregister running tools with state manager.

Parameters:

ti_list : list of ToolInstance instances

List of registered running tool instances.

reset_state(session)

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)

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)

Start tools that are specified by name.

take_snapshot(session, flags)

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.