You are reading an old version of the documentation (v2.0.2). For the latest version see https://matplotlib.org/stable/api/backend_tools_api.html
matplotlib

Travis-CI:

This Page

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)

Bases: matplotlib.backend_tools.ToolToggleBase

Base Tool to toggle between linear and logarithmic

disable(event)
enable(event)
trigger(sender, event, data=None)
class matplotlib.backend_tools.ConfigureSubplotsBase(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Base tool for the configuration of subplots

description = 'Configure subplots'
image = 'subplots.png'
class matplotlib.backend_tools.Cursors

Bases: object

Simple namespace for cursor reference

HAND = 0
MOVE = 3
POINTER = 1
SELECT_REGION = 2
class matplotlib.backend_tools.RubberbandBase(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Draw and remove rubberband

draw_rubberband(*data)

Draw rubberband

This method must get implemented per backend

remove_rubberband()

Remove rubberband

This method should get implemented per backend

trigger(sender, event, data)

Call draw_rubberband or remove_rubberband based on data

class matplotlib.backend_tools.SaveFigureBase(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Base tool for figure saving

default_keymap = ['s', 'ctrl+s']
description = 'Save the figure'
image = 'filesave.png'
class matplotlib.backend_tools.SetCursorBase(*args, **kwargs)

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)

Set the cursor

This method has to be implemented per backend

class matplotlib.backend_tools.ToolBack(toolmanager, name)

Bases: matplotlib.backend_tools.ViewsPositionsBase

Move back up the view lim stack

default_keymap = ['left', 'c', 'backspace']
description = 'Back to previous view'
image = 'back.png'
class matplotlib.backend_tools.ToolBase(toolmanager, name)

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

toolmanager: matplotlib.backend_managers.ToolManager ToolManager that controls this Tool
figure: FigureCanvas Figure instance that is affected by this Tool
name: String Used as Id of the tool, has to be unique among tools of the same ToolManager
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 emited

description = None

Description of the Tool

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

destroy()

Destroy the tool

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

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

name

Tool Id

trigger(sender, event, data=None)

Called when this tool gets used

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

Parameters:

event: `Event`

The Canvas event that caused this tool to be called

sender: object

Object that requested the tool to be triggered

data: object

Extra data

class matplotlib.backend_tools.ToolCursorPosition(*args, **kwargs)

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)

Call matplotlib.backend_managers.ToolManager.message_event

class matplotlib.backend_tools.ToolEnableAllNavigation(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Tool to enable all axes for toolmanager interaction

default_keymap = ['a']
description = 'Enables all axes toolmanager'
trigger(sender, event, data=None)
class matplotlib.backend_tools.ToolEnableNavigation(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Tool to enable a specific axes for toolmanager interaction

default_keymap = (1, 2, 3, 4, 5, 6, 7, 8, 9)
description = 'Enables one axes toolmanager'
trigger(sender, event, data=None)
class matplotlib.backend_tools.ToolForward(toolmanager, name)

Bases: matplotlib.backend_tools.ViewsPositionsBase

Move forward in the view lim stack

default_keymap = ['right', 'v']
description = 'Forward to next view'
image = 'forward.png'
class matplotlib.backend_tools.ToolFullScreen(*args, **kwargs)

Bases: matplotlib.backend_tools.ToolToggleBase

Tool to toggle full screen

default_keymap = ['f', 'ctrl+f']
description = 'Toogle Fullscreen mode'
disable(event)
enable(event)
class matplotlib.backend_tools.ToolGrid(*args, **kwargs)

Bases: matplotlib.backend_tools.ToolToggleBase

Tool to toggle the grid of the figure

default_keymap = ['g']
description = 'Toogle Grid'
disable(event)
enable(event)
trigger(sender, event, data=None)
class matplotlib.backend_tools.ToolHome(toolmanager, name)

Bases: matplotlib.backend_tools.ViewsPositionsBase

Restore the original view lim

default_keymap = ['h', 'r', 'home']
description = 'Reset original view'
image = 'home.png'
class matplotlib.backend_tools.ToolPan(*args)

Bases: matplotlib.backend_tools.ZoomPanBase

Pan axes with left mouse, zoom with right

cursor = 3
default_keymap = ['p']
description = 'Pan axes with left mouse, zoom with right'
image = 'move.png'
radio_group = 'default'
class matplotlib.backend_tools.ToolQuit(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Tool to call the figure manager destroy method

default_keymap = ['ctrl+w', 'cmd+w']
description = 'Quit the figure'
trigger(sender, event, data=None)
class matplotlib.backend_tools.ToolToggleBase(*args, **kwargs)

Bases: matplotlib.backend_tools.ToolBase

Toggleable tool

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

cursor = None

Cursor to use when the tool is active

disable(event=None)

Disable the toggle tool

trigger call this method when toggled is True.

This can happen in different circumstances

enable(event=None)

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

toggled

State of the toggled tool

trigger(sender, event, data=None)

Calls enable or disable based on toggled value

class matplotlib.backend_tools.ToolViewsPositions(*args, **kwargs)

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()

Add the current figure to the stack of views and positions

back()

Back one step in the stack of views and positions

clear(figure)

Reset the axes stack

forward()

Forward one step in the stack of views and positions

home()

Recall the first view and position from the stack

push_current()

push the current view limits and position onto the stack

refresh_locators()

Redraw the canvases, update the locators

update_view()

Update the viewlim and position from the view and position stack for each axes

class matplotlib.backend_tools.ToolXScale(*args, **kwargs)

Bases: matplotlib.backend_tools.AxisScaleBase

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

default_keymap = ['k', 'L']
description = 'Toogle Scale X axis'
set_scale(ax, scale)
class matplotlib.backend_tools.ToolYScale(*args, **kwargs)

Bases: matplotlib.backend_tools.AxisScaleBase

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

default_keymap = ['l']
description = 'Toogle Scale Y axis'
set_scale(ax, scale)
class matplotlib.backend_tools.ToolZoom(*args)

Bases: matplotlib.backend_tools.ZoomPanBase

Zoom to rectangle

cursor = 2
default_keymap = ['o']
description = 'Zoom to rectangle'
image = 'zoom_to_rect.png'
radio_group = 'default'
class matplotlib.backend_tools.ViewsPositionsBase(toolmanager, name)

Bases: matplotlib.backend_tools.ToolBase

Base class for ToolHome, ToolBack and ToolForward

trigger(sender, event, data=None)
class matplotlib.backend_tools.ZoomPanBase(*args)

Bases: matplotlib.backend_tools.ToolToggleBase

Base class for ToolZoom and ToolPan

disable(event)

Release the canvas and disconnect press/release events

enable(event)

Connect press/release events and lock the canvas

scroll_zoom(event)
trigger(sender, event, data=None)
matplotlib.backend_tools.add_tools_to_container(container, tools=[['navigation', ['home', 'back', 'forward']], ['zoompan', ['pan', 'zoom', 'subplots']], ['io', ['save']]])

Add multiple tools to the container.

Parameters:

container: Container

backend_bases.ToolContainerBase object that will get the tools added

tools : list, optional

List in the form [[group1, [tool1, tool2 ...]], [group2, [...]]] Where the tools given by tool1, and tool2 will display in group1. See add_tool for details.

matplotlib.backend_tools.add_tools_to_manager(toolmanager, tools={'home': <class 'matplotlib.backend_tools.ToolHome'>, 'back': <class 'matplotlib.backend_tools.ToolBack'>, 'forward': <class 'matplotlib.backend_tools.ToolForward'>, 'zoom': <class 'matplotlib.backend_tools.ToolZoom'>, 'pan': <class 'matplotlib.backend_tools.ToolPan'>, 'subplots': 'ToolConfigureSubplots', 'save': 'ToolSaveFigure', 'grid': <class 'matplotlib.backend_tools.ToolGrid'>, 'fullscreen': <class 'matplotlib.backend_tools.ToolFullScreen'>, 'quit': <class 'matplotlib.backend_tools.ToolQuit'>, 'allnav': <class 'matplotlib.backend_tools.ToolEnableAllNavigation'>, 'nav': <class 'matplotlib.backend_tools.ToolEnableNavigation'>, 'xscale': <class 'matplotlib.backend_tools.ToolXScale'>, 'yscale': <class 'matplotlib.backend_tools.ToolYScale'>, 'position': <class 'matplotlib.backend_tools.ToolCursorPosition'>, 'viewpos': <class 'matplotlib.backend_tools.ToolViewsPositions'>, 'cursor': 'ToolSetCursor', 'rubberband': 'ToolRubberband'})

Add multiple tools to ToolManager

Parameters:

toolmanager: ToolManager

backend_managers.ToolManager object that will get the tools added

tools : {str: class_like}, optional

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

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

Default tools in the toolbar

matplotlib.backend_tools.default_tools = {'home': <class 'matplotlib.backend_tools.ToolHome'>, 'back': <class 'matplotlib.backend_tools.ToolBack'>, 'forward': <class 'matplotlib.backend_tools.ToolForward'>, 'zoom': <class 'matplotlib.backend_tools.ToolZoom'>, 'pan': <class 'matplotlib.backend_tools.ToolPan'>, 'subplots': 'ToolConfigureSubplots', 'save': 'ToolSaveFigure', 'grid': <class 'matplotlib.backend_tools.ToolGrid'>, 'fullscreen': <class 'matplotlib.backend_tools.ToolFullScreen'>, 'quit': <class 'matplotlib.backend_tools.ToolQuit'>, 'allnav': <class 'matplotlib.backend_tools.ToolEnableAllNavigation'>, 'nav': <class 'matplotlib.backend_tools.ToolEnableNavigation'>, 'xscale': <class 'matplotlib.backend_tools.ToolXScale'>, 'yscale': <class 'matplotlib.backend_tools.ToolYScale'>, 'position': <class 'matplotlib.backend_tools.ToolCursorPosition'>, 'viewpos': <class 'matplotlib.backend_tools.ToolViewsPositions'>, 'cursor': 'ToolSetCursor', 'rubberband': 'ToolRubberband'}

Default tools