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.delete_handler.
-
class
ToolInstance
(session, tool_info, id=None, **kw)¶ Bases:
chimera.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 chimera.core.session.Session
Session in which this tool instance was created.
tool_info : a
ToolInfo
instanceThe 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. Defaults to tool_info.display_name
.SESSION_ENDURING (bool, class-level optional) If True, then tool survives across sessions. SESSION_SKIP (bool, class-level optional) If True, then tool is not saved in sessions. -
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.
-
session
¶ Read-only property for session that contains this tool instance.
-
-
class
Tools
(session)¶ Bases:
chimera.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
()¶ Reset state manager to default state.
Overrides chimera.core.session.State default method to reset to default state. Since the default state has no running tools, all registered tool instances are deleted.
-
restore_snapshot
(phase, session, version, data)¶ Restore state of running tools.
Overrides chimera.core.session.State default method to restore state of all registered running tools.
Parameters: phase : str
Restoration phase. See chimera.core.session for more details.
session : instance of chimera.core.session.Session
Session for which state is being saved. Should match the session argument given to __init__.
version : any
Version of state manager that saved the data. Used for determining how to parse the data argument.
data : any
Data saved by state manager during take_snapshot.
-
take_snapshot
(phase, session, flags)¶ Save state of running tools.
Overrides chimera.core.session.State default method to save state of all registered running tool instances.
Parameters: session : instance of chimera.core.session.Session
Session for which state is being saved. Should match the session argument given to __init__.
phase : str
Take phase. See chimera.core.session for more details.
flags : int
Flags indicating whether snapshot is being taken to save scene or session. See chimera.core.session for more details.
-