tools: Manage running tool instances¶
This module defines classes for running tools and their state manager.
Name of trigger that is fired when a new tool registers with the state manager.
Name of trigger that is fired when a running tool deregisters with the state manager.
‘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)¶
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.
If a different name is desired (e.g. multi-instance tool) make sure to set the attribute before creating the first tool window.
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.
Experimental API . Show or hide this tool instance in the user interface.
b (boolean) – Boolean value for whether the tool should be shown or hidden.
- 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)¶
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.
Experimental API . Register running tools with state manager.
ti_list (list of ToolInstance instances) – List of newly created running tool instances.
Experimental API . Return a list of tools of the given class.
All tool instances that match cls as defined by isinstance are returned.
cls (class object) – Class object used to match tool instances.
Experimental API . Return list of running tools.
List of ToolInstance instances.
- Return type:
Experimental API . Deregister running tools with state manager.
ti_list (list of ToolInstance instances) – List of registered running tool instances.
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.
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.
- 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.
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.