matplotlib.backend_tools

Abstract base classes define the primitives for Tools. These tools are used by matplotlib.backend_managers.ToolManager

ToolBase
Simple stateless tool
ToolToggleBase
Tool that has two states, only one Toggle tool can be active at any given time for the same matplotlib.backend_managers.ToolManager
class matplotlib.backend_tools.AxisScaleBase(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.ToolToggleBase

Base Tool to toggle between linear and logarithmic.

disable(event)[source]

Disable the toggle tool.

trigger call this method when toggled is True.

This can happen in different circumstances.

enable(event)[source]

Enable the toggle tool.

trigger calls this method when toggled is False.

trigger(sender, event, data=None)[source]

Calls enable or disable based on toggled value.

class matplotlib.backend_tools.ConfigureSubplotsBase(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Base tool for the configuration of subplots.

description = 'Configure subplots'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'subplots'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

class matplotlib.backend_tools.Cursors(value)[source]

Bases: enum.IntEnum

Backend-independent cursor types.

HAND = 0
MOVE = 3
POINTER = 1
SELECT_REGION = 2
WAIT = 4
class matplotlib.backend_tools.RubberbandBase(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Draw and remove a rubberband.

draw_rubberband(*data)[source]

Draw rubberband.

This method must get implemented per backend.

remove_rubberband()[source]

Remove rubberband.

This method should get implemented per backend.

trigger(sender, event, data)[source]

Call draw_rubberband or remove_rubberband based on data.

class matplotlib.backend_tools.SaveFigureBase(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Base tool for figure saving.

default_keymap = ['s', 'ctrl+s']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Save the figure'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'filesave'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

class matplotlib.backend_tools.SetCursorBase(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.ToolBase

Change to the current cursor while inaxes.

This tool, keeps track of all ToolToggleBase derived tools, and calls set_cursor when a tool gets triggered.

set_cursor(cursor)[source]

Set the cursor.

This method has to be implemented per backend.

set_figure(figure)[source]

Assign a figure to the tool.

Parameters:
figureFigure
class matplotlib.backend_tools.ToolBack(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ViewsPositionsBase

Move back up the view limits stack.

default_keymap = ['left', 'c', 'backspace', 'MouseButton.BACK']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Back to previous view'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'back'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

class matplotlib.backend_tools.ToolBase(toolmanager, name)[source]

Bases: object

Base tool class.

A base tool, only implements trigger method or not method at all. The tool is instantiated by matplotlib.backend_managers.ToolManager.

Attributes:
toolmanagermatplotlib.backend_managers.ToolManager

ToolManager that controls this Tool.

figureFigureCanvas

Figure instance that is affected by this Tool.

namestr

Tool Id.

property canvas
default_keymap = None

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = None

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

destroy()[source]

Destroy the tool.

This method is called when the tool is removed by matplotlib.backend_managers.ToolManager.remove_tool.

property figure
image = None

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

property name

Tool Id.

set_figure(figure)[source]

Assign a figure to the tool.

Parameters:
figureFigure
property toolmanager
trigger(sender, event, data=None)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

matplotlib.backend_tools.ToolCopyToClipboard

alias of matplotlib.backend_tools.ToolCopyToClipboardBase

class matplotlib.backend_tools.ToolCopyToClipboardBase(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Tool to copy the figure to the clipboard.

default_keymap = ['ctrl+c', 'cmd+c']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Copy the canvas figure to clipboard'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

trigger(*args, **kwargs)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

class matplotlib.backend_tools.ToolCursorPosition(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.ToolBase

Send message with the current pointer position.

This tool runs in the background reporting the position of the cursor.

send_message(event)[source]

Call matplotlib.backend_managers.ToolManager.message_event.

set_figure(figure)[source]

Assign a figure to the tool.

Parameters:
figureFigure
class matplotlib.backend_tools.ToolEnableAllNavigation(toolmanager, name)[source]

Bases: matplotlib.backend_tools._ToolEnableAllNavigation

[Deprecated]

Notes

Deprecated since version 3.3:

class matplotlib.backend_tools.ToolEnableNavigation(toolmanager, name)[source]

Bases: matplotlib.backend_tools._ToolEnableNavigation

[Deprecated]

Notes

Deprecated since version 3.3:

class matplotlib.backend_tools.ToolForward(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ViewsPositionsBase

Move forward in the view lim stack.

default_keymap = ['right', 'v', 'MouseButton.FORWARD']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Forward to next view'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'forward'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

class matplotlib.backend_tools.ToolFullScreen(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.ToolToggleBase

Tool to toggle full screen.

default_keymap = ['f', 'ctrl+f']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Toggle fullscreen mode'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

disable(event)[source]

Disable the toggle tool.

trigger call this method when toggled is True.

This can happen in different circumstances.

enable(event)[source]

Enable the toggle tool.

trigger calls this method when toggled is False.

class matplotlib.backend_tools.ToolGrid(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Tool to toggle the major grids of the figure.

default_keymap = ['g']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Toggle major grids'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

trigger(sender, event, data=None)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

class matplotlib.backend_tools.ToolHelpBase(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

default_keymap = ['f1']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Print tool list, shortcuts and description'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

static format_shortcut(key_sequence)[source]

Converts a shortcut string from the notation used in rc config to the standard notation for displaying shortcuts, e.g. 'ctrl+a' -> 'Ctrl+A'.

image = 'help'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

class matplotlib.backend_tools.ToolHome(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ViewsPositionsBase

Restore the original view limits.

default_keymap = ['h', 'r', 'home']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Reset original view'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'home'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

class matplotlib.backend_tools.ToolMinorGrid(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Tool to toggle the major and minor grids of the figure.

default_keymap = ['G']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Toggle major and minor grids'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

trigger(sender, event, data=None)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

class matplotlib.backend_tools.ToolPan(*args)[source]

Bases: matplotlib.backend_tools.ZoomPanBase

Pan axes with left mouse, zoom with right.

cursor = 3

Cursor to use when the tool is active.

default_keymap = ['p']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Pan axes with left mouse, zoom with right'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'move'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

radio_group = 'default'

Attribute to group 'radio' like tools (mutually exclusive).

String that identifies the group or None if not belonging to a group.

class matplotlib.backend_tools.ToolQuit(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Tool to call the figure manager destroy method.

default_keymap = ['ctrl+w', 'cmd+w', 'q']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Quit the figure'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

trigger(sender, event, data=None)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

class matplotlib.backend_tools.ToolQuitAll(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Tool to call the figure manager destroy method.

default_keymap = []

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Quit all figures'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

trigger(sender, event, data=None)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

class matplotlib.backend_tools.ToolToggleBase(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.ToolBase

Toggleable tool.

Every time it is triggered, it switches between enable and disable.

Parameters:
``*args``

Variable length argument to be used by the Tool.

``**kwargs``

toggled if present and True, sets the initial state of the Tool Arbitrary keyword arguments to be consumed by the Tool

cursor = None

Cursor to use when the tool is active.

default_toggled = False

Default of toggled state.

disable(event=None)[source]

Disable the toggle tool.

trigger call this method when toggled is True.

This can happen in different circumstances.

enable(event=None)[source]

Enable the toggle tool.

trigger calls this method when toggled is False.

radio_group = None

Attribute to group 'radio' like tools (mutually exclusive).

String that identifies the group or None if not belonging to a group.

set_figure(figure)[source]

Assign a figure to the tool.

Parameters:
figureFigure
property toggled

State of the toggled tool.

trigger(sender, event, data=None)[source]

Calls enable or disable based on toggled value.

class matplotlib.backend_tools.ToolViewsPositions(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.ToolBase

Auxiliary Tool to handle changes in views and positions.

Runs in the background and should get used by all the tools that need to access the figure's history of views and positions, e.g.

add_figure(figure)[source]

Add the current figure to the stack of views and positions.

back()[source]

Back one step in the stack of views and positions.

clear(figure)[source]

Reset the axes stack.

forward()[source]

Forward one step in the stack of views and positions.

home()[source]

Recall the first view and position from the stack.

push_current(figure=None)[source]

Push the current view limits and position onto their respective stacks.

refresh_locators()[source]

[Deprecated] Redraw the canvases, update the locators.

Notes

Deprecated since version 3.3.

update_home_views(figure=None)[source]

Make sure that self.home_views has an entry for all axes present in the figure.

update_view()[source]

Update the view limits and position for each axes from the current stack position. If any axes are present in the figure that aren't in the current stack position, use the home view limits for those axes and don't update any positions.

class matplotlib.backend_tools.ToolXScale(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.AxisScaleBase

Tool to toggle between linear and logarithmic scales on the X axis.

default_keymap = ['k', 'L']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Toggle scale X axis'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

set_scale(ax, scale)[source]
class matplotlib.backend_tools.ToolYScale(*args, **kwargs)[source]

Bases: matplotlib.backend_tools.AxisScaleBase

Tool to toggle between linear and logarithmic scales on the Y axis.

default_keymap = ['l']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Toggle scale Y axis'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

set_scale(ax, scale)[source]
class matplotlib.backend_tools.ToolZoom(*args)[source]

Bases: matplotlib.backend_tools.ZoomPanBase

A Tool for zooming using a rectangle selector.

cursor = 2

Cursor to use when the tool is active.

default_keymap = ['o']

Keymap to associate with this tool.

String: List of comma separated keys that will be used to call this tool when the keypress event of self.figure.canvas is emitted.

description = 'Zoom to rectangle'

Description of the Tool.

String: If the Tool is included in the Toolbar this text is used as a Tooltip.

image = 'zoom_to_rect'

Filename of the image.

String: Filename of the image to use in the toolbar. If None, the name is used as a label in the toolbar button.

radio_group = 'default'

Attribute to group 'radio' like tools (mutually exclusive).

String that identifies the group or None if not belonging to a group.

class matplotlib.backend_tools.ViewsPositionsBase(toolmanager, name)[source]

Bases: matplotlib.backend_tools.ToolBase

Base class for ToolHome, ToolBack and ToolForward.

trigger(sender, event, data=None)[source]

Called when this tool gets used.

This method is called by matplotlib.backend_managers.ToolManager.trigger_tool.

Parameters:
eventEvent

The canvas event that caused this tool to be called.

senderobject

Object that requested the tool to be triggered.

dataobject

Extra data.

class matplotlib.backend_tools.ZoomPanBase(*args)[source]

Bases: matplotlib.backend_tools.ToolToggleBase

Base class for ToolZoom and ToolPan.

disable(event)[source]

Release the canvas and disconnect press/release events.

enable(event)[source]

Connect press/release events and lock the canvas.

scroll_zoom(event)[source]
trigger(sender, event, data=None)[source]

Calls enable or disable based on toggled value.

matplotlib.backend_tools.add_tools_to_container(container, tools=[['navigation', ['home', 'back', 'forward']], ['zoompan', ['pan', 'zoom', 'subplots']], ['io', ['save', 'help']]])[source]

Add multiple tools to the container.

Parameters:
containerContainer

backend_bases.ToolContainerBase object that will get the tools added.

toolslist, optional

List in the form [[group1, [tool1, tool2 ...]], [group2, [...]]] where the tools [tool1, tool2, ...] will display in group1. See add_tool for details.

matplotlib.backend_tools.add_tools_to_manager(toolmanager, tools={'allnav': <class 'matplotlib.backend_tools._ToolEnableAllNavigation'>, 'back': <class 'matplotlib.backend_tools.ToolBack'>, 'copy': 'ToolCopyToClipboard', 'cursor': 'ToolSetCursor', 'forward': <class 'matplotlib.backend_tools.ToolForward'>, 'fullscreen': <class 'matplotlib.backend_tools.ToolFullScreen'>, 'grid': <class 'matplotlib.backend_tools.ToolGrid'>, 'grid_minor': <class 'matplotlib.backend_tools.ToolMinorGrid'>, 'help': 'ToolHelp', 'home': <class 'matplotlib.backend_tools.ToolHome'>, 'nav': <class 'matplotlib.backend_tools._ToolEnableNavigation'>, 'pan': <class 'matplotlib.backend_tools.ToolPan'>, 'position': <class 'matplotlib.backend_tools.ToolCursorPosition'>, 'quit': <class 'matplotlib.backend_tools.ToolQuit'>, 'quit_all': <class 'matplotlib.backend_tools.ToolQuitAll'>, 'rubberband': 'ToolRubberband', 'save': 'ToolSaveFigure', 'subplots': 'ToolConfigureSubplots', 'viewpos': <class 'matplotlib.backend_tools.ToolViewsPositions'>, 'xscale': <class 'matplotlib.backend_tools.ToolXScale'>, 'yscale': <class 'matplotlib.backend_tools.ToolYScale'>, 'zoom': <class 'matplotlib.backend_tools.ToolZoom'>})[source]

Add multiple tools to a ToolManager.

Parameters:
toolmanagerbackend_managers.ToolManager

Manager to which the tools are added.

tools{str: class_like}, optional

The tools to add in a {name: tool} dict, see add_tool for more info.

matplotlib.backend_tools.cursors

alias of matplotlib.backend_tools.Cursors

matplotlib.backend_tools.default_toolbar_tools = [['navigation', ['home', 'back', 'forward']], ['zoompan', ['pan', 'zoom', 'subplots']], ['io', ['save', 'help']]]

Default tools in the toolbar

matplotlib.backend_tools.default_tools = {'allnav': <class 'matplotlib.backend_tools._ToolEnableAllNavigation'>, 'back': <class 'matplotlib.backend_tools.ToolBack'>, 'copy': 'ToolCopyToClipboard', 'cursor': 'ToolSetCursor', 'forward': <class 'matplotlib.backend_tools.ToolForward'>, 'fullscreen': <class 'matplotlib.backend_tools.ToolFullScreen'>, 'grid': <class 'matplotlib.backend_tools.ToolGrid'>, 'grid_minor': <class 'matplotlib.backend_tools.ToolMinorGrid'>, 'help': 'ToolHelp', 'home': <class 'matplotlib.backend_tools.ToolHome'>, 'nav': <class 'matplotlib.backend_tools._ToolEnableNavigation'>, 'pan': <class 'matplotlib.backend_tools.ToolPan'>, 'position': <class 'matplotlib.backend_tools.ToolCursorPosition'>, 'quit': <class 'matplotlib.backend_tools.ToolQuit'>, 'quit_all': <class 'matplotlib.backend_tools.ToolQuitAll'>, 'rubberband': 'ToolRubberband', 'save': 'ToolSaveFigure', 'subplots': 'ToolConfigureSubplots', 'viewpos': <class 'matplotlib.backend_tools.ToolViewsPositions'>, 'xscale': <class 'matplotlib.backend_tools.ToolXScale'>, 'yscale': <class 'matplotlib.backend_tools.ToolYScale'>, 'zoom': <class 'matplotlib.backend_tools.ToolZoom'>}

Default tools