You are reading documentation for the unreleased version of Matplotlib. Try searching for the released version of this page instead?
Applications are open for the 2018 John Hunter Matplotlib Summer Fellowship. Apply now!
Version 2.2.2.post1744+g9382a0569
matplotlib
Fork me on GitHub

matplotlib.backend_managers

ToolManager
Class that makes the bridge between user interaction (key press, toolbar clicks, ..) and the actions in response to the user inputs.
class matplotlib.backend_managers.ToolEvent(name, sender, tool, data=None)[source]

Bases: object

Event for tool manipulation (add/remove)

class matplotlib.backend_managers.ToolManager(figure=None)[source]

Bases: object

Helper class that groups all the user interactions for a Figure.

Attributes:
figure: `Figure`
keypresslock: `widgets.LockDraw`

LockDraw object to know if the canvas key_press_event is locked

messagelock: `widgets.LockDraw`

LockDraw object to know if the message is available to write

active_toggle

Currently toggled tools

add_tool(name, tool, *args, **kwargs)[source]

Add tool to ToolManager

If successful adds a new event tool_trigger_name where name is the name of the tool, this event is fired everytime the tool is triggered.

Parameters:
name : str

Name of the tool, treated as the ID, has to be unique

tool : class_like, i.e. str or type

Reference to find the class of the Tool to added.

See also

matplotlib.backend_tools.ToolBase
The base class for tools.

Notes

args and kwargs get passed directly to the tools constructor.

canvas

Canvas managed by FigureManager

figure

Figure that holds the canvas

get_tool(name, warn=True)[source]

Return the tool object, also accepts the actual tool for convenience

Parameters:
name : str, ToolBase

Name of the tool, or the tool itself

warn : bool, optional

If this method should give warnings.

get_tool_keymap(name)[source]

Get the keymap associated with the specified tool

Parameters:
name : string

Name of the Tool

Returns:
list : list of keys associated with the Tool
message_event(message, sender=None)[source]

Emit a ToolManagerMessageEvent

remove_tool(name)[source]

Remove tool from ToolManager

Parameters:
name : string

Name of the Tool

set_figure(figure, update_tools=True)[source]

Bind the given figure to the tools.

Parameters:
figure : Figure
update_tools : bool

Force tools to update figure

toolmanager_connect(s, func)[source]

Connect event with string s to func.

Parameters:
s : String

Name of the event

The following events are recognized

  • 'tool_message_event'
  • 'tool_removed_event'
  • 'tool_added_event'

For every tool added a new event is created

  • 'tool_trigger_TOOLNAME` Where TOOLNAME is the id of the tool.
func : function

Function to be called with signature def func(event)

toolmanager_disconnect(cid)[source]

Disconnect callback id cid

Example usage:

cid = toolmanager.toolmanager_connect('tool_trigger_zoom',
                                      on_press)
#...later
toolmanager.toolmanager_disconnect(cid)
tools

Return the tools controlled by ToolManager

trigger_tool(name, sender=None, canvasevent=None, data=None)[source]

Trigger a tool and emit the tool_trigger_[name] event

Parameters:
name : string

Name of the tool

sender: object

Object that wishes to trigger the tool

canvasevent : Event

Original Canvas event or None

data : Object

Extra data to pass to the tool when triggering

update_keymap(name, *keys)[source]

Set the keymap to associate with the specified tool

Parameters:
name : string

Name of the Tool

keys : keys to associate with the Tool
class matplotlib.backend_managers.ToolManagerMessageEvent(name, sender, message)[source]

Bases: object

Event carrying messages from toolmanager

Messages usually get displayed to the user by the toolbar

class matplotlib.backend_managers.ToolTriggerEvent(name, sender, tool, canvasevent=None, data=None)[source]

Bases: matplotlib.backend_managers.ToolEvent

Event to inform that a tool has been triggered