tools: Manage running tool instances

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

ADD_TOOL_INSTANCE

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

Type:

str

REMOVE_TOOL_INSTANCE

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

Type:

str

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:
display_name

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

Type:

str

SESSION_ENDURING

If True, then tool survives across sessions.

Type:

bool, class-level optional

SESSION_SAVE

If False, then tool is not saved in sessions.

Type:

bool, class-level optional

help

URL for tool’s help

Type:

str

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.

property session

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.

list()

Experimental API . Return list of running tools.

Returns:

List of ToolInstance instances.

Return type:

list

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.