matplotlib.backend_tools#

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

ToolBase

Simple stateless tool

ToolToggleBase

Tool that has two states, only one Toggle tool can beactive at any given time for the samematplotlib.backend_managers.ToolManager

classmatplotlib.backend_tools.AxisScaleBase(*args,**kwargs)[source]#

Bases:ToolToggleBase

Base Tool to toggle between linear and logarithmic.

disable(event=None)[source]#

Disable the toggle tool.

trigger call this method whentoggled is True.

This can happen in different circumstances.

• Click on the toolbar tool button.

• Call tomatplotlib.backend_managers.ToolManager.trigger_tool.

• AnotherToolToggleBase derived tool is triggered(from the sameToolManager).

enable(event=None)[source]#

Enable the toggle tool.

trigger calls this method whentoggled is False.

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

Callsenable ordisable based ontoggled value.

classmatplotlib.backend_tools.ConfigureSubplotsBase(toolmanager,name)[source]#

Bases:ToolBase

Base tool for the configuration of subplots.

description='Configuresubplots'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/subplots'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

classmatplotlib.backend_tools.Cursors(*values)[source]#

Bases:IntEnum

Backend-independent cursor types.

HAND=2[source]#

MOVE=4[source]#

POINTER=1[source]#

RESIZE_HORIZONTAL=6[source]#

RESIZE_VERTICAL=7[source]#

SELECT_REGION=3[source]#

WAIT=5[source]#

classmatplotlib.backend_tools.RubberbandBase(toolmanager,name)[source]#

Bases: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=None)[source]#

Calldraw_rubberband orremove_rubberband based on data.

classmatplotlib.backend_tools.SaveFigureBase(toolmanager,name)[source]#

Bases:ToolBase

Base tool for figure saving.

propertydefault_keymap#

The type of the None singleton.

description='Savethefigure'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/filesave'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

classmatplotlib.backend_tools.ToolBack(toolmanager,name)[source]#

Bases:ViewsPositionsBase

Move back up the view limits stack.

propertydefault_keymap#

The type of the None singleton.

description='Backtopreviousview'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/back'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

classmatplotlib.backend_tools.ToolBase(toolmanager,name)[source]#

Bases:object

Base tool class.

A base tool, only implementstrigger method or no method at all.The tool is instantiated bymatplotlib.backend_managers.ToolManager.

propertycanvas#

The canvas of the figure affected by this tool, or None.

default_keymap=None#

Keymap to associate with this tool.

list[str]: List of keys that will trigger this tool when a keypressevent is emitted onself.figure.canvas. Note that this attribute islooked up on the instance, and can therefore be a property (this is usede.g. by the built-in tools to load the rcParams at instantiation time).

description=None#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

propertyfigure#

The Figure affected by this tool, or None.

image=None#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

propertyname#

The tool id (str, must be unique among tools of a tool manager).

set_figure(figure)[source]#

propertytoolmanager#

TheToolManager that controls this tool.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolCopyToClipboardBase(toolmanager,name)[source]#

Bases:ToolBase

Tool to copy the figure to the clipboard.

propertydefault_keymap#

The type of the None singleton.

description='Copythecanvasfiguretoclipboard'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolCursorPosition(*args,**kwargs)[source]#

Bases:ToolBase

Send message with the current pointer position.

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

send_message(event)[source]#

Callmatplotlib.backend_managers.ToolManager.message_event.

set_figure(figure)[source]#

classmatplotlib.backend_tools.ToolForward(toolmanager,name)[source]#

Bases:ViewsPositionsBase

Move forward in the view lim stack.

propertydefault_keymap#

The type of the None singleton.

description='Forwardtonextview'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/forward'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

classmatplotlib.backend_tools.ToolFullScreen(toolmanager,name)[source]#

Bases:ToolBase

Tool to toggle full screen.

propertydefault_keymap#

The type of the None singleton.

description='Togglefullscreenmode'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolGrid(toolmanager,name)[source]#

Bases:ToolBase

Tool to toggle the major grids of the figure.

propertydefault_keymap#

The type of the None singleton.

description='Togglemajorgrids'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolHelpBase(toolmanager,name)[source]#

Bases:ToolBase

propertydefault_keymap#

The type of the None singleton.

description='Printtoollist,shortcutsanddescription'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

staticformat_shortcut(key_sequence)[source]#

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

image='mpl-data/images/help'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

classmatplotlib.backend_tools.ToolHome(toolmanager,name)[source]#

Bases:ViewsPositionsBase

Restore the original view limits.

propertydefault_keymap#

The type of the None singleton.

description='Resetoriginalview'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/home'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

classmatplotlib.backend_tools.ToolMinorGrid(toolmanager,name)[source]#

Bases:ToolBase

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

propertydefault_keymap#

The type of the None singleton.

description='Togglemajorandminorgrids'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolPan(*args)[source]#

Bases:ZoomPanBase

Pan Axes with left mouse, zoom with right.

cursor=4[source]#

Cursor to use when the tool is active.

propertydefault_keymap#

The type of the None singleton.

description='Panaxeswithleftmouse,zoomwithright'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/move'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

radio_group='default'#

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

str that identifies the group orNone if not belonging to a group.

classmatplotlib.backend_tools.ToolQuit(toolmanager,name)[source]#

Bases:ToolBase

Tool to call the figure manager destroy method.

propertydefault_keymap#

The type of the None singleton.

description='Quitthefigure'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolQuitAll(toolmanager,name)[source]#

Bases:ToolBase

Tool to call the figure manager destroy method.

propertydefault_keymap#

The type of the None singleton.

description='Quitallfigures'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ToolSetCursor(*args,**kwargs)[source]#

Bases:ToolBase

Change to the current cursor while inaxes.

This tool, keeps track of allToolToggleBase derived tools, and updatesthe cursor when a tool gets triggered.

set_figure(figure)[source]#

classmatplotlib.backend_tools.ToolToggleBase(*args,**kwargs)[source]#

Bases: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 ToolArbitrary 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 whentoggled is True.

This can happen in different circumstances.

• Click on the toolbar tool button.

• Call tomatplotlib.backend_managers.ToolManager.trigger_tool.

• AnotherToolToggleBase derived tool is triggered(from the sameToolManager).

enable(event=None)[source]#

Enable the toggle tool.

trigger calls this method whentoggled is False.

radio_group=None#

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

str that identifies the group orNone if not belonging to a group.

set_figure(figure)[source]#

propertytoggled#

State of the toggled tool.

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

Callsenable ordisable based ontoggled value.

classmatplotlib.backend_tools.ToolViewsPositions(*args,**kwargs)[source]#

Bases:ToolBase

Auxiliary Tool to handle changes in views and positions.

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

• ToolZoom

• ToolPan

• ToolHome

• ToolBack

• ToolForward

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.

update_home_views(figure=None)[source]#

Make sure thatself.home_views has an entry for all Axes presentin the figure.

update_view()[source]#

Update the view limits and position for each Axes from the currentstack position. If any Axes are present in the figure that aren't inthe current stack position, use the home view limits for those Axes anddon't updateany positions.

classmatplotlib.backend_tools.ToolXScale(*args,**kwargs)[source]#

Bases:AxisScaleBase

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

propertydefault_keymap#

The type of the None singleton.

description='TogglescaleXaxis'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

set_scale(ax,scale)[source]#

classmatplotlib.backend_tools.ToolYScale(*args,**kwargs)[source]#

Bases:AxisScaleBase

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

propertydefault_keymap#

The type of the None singleton.

description='TogglescaleYaxis'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

set_scale(ax,scale)[source]#

classmatplotlib.backend_tools.ToolZoom(*args)[source]#

Bases:ZoomPanBase

A Tool for zooming using a rectangle selector.

cursor=3[source]#

Cursor to use when the tool is active.

propertydefault_keymap#

The type of the None singleton.

description='Zoomtorectangle'#

Description of the Tool.

str: Tooltip used if the Tool is included in a Toolbar.

image='mpl-data/images/zoom_to_rect'#

Icon filename.

str|None: Filename of the Toolbar icon; either absolute, or relative to thedirectory containing the Python source file where theTool.image class attributeis defined (in the latter case, this cannot be defined as an instance attribute).In either case, the extension is optional; leaving it off lets individual backendsselect the icon format they prefer. If None, thename is used as a label in thetoolbar button.

radio_group='default'#

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

str that identifies the group orNone if not belonging to a group.

classmatplotlib.backend_tools.ViewsPositionsBase(toolmanager,name)[source]#

Bases:ToolBase

Base class forToolHome,ToolBack andToolForward.

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

Called when this tool gets used.

This method is called byToolManager.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.

classmatplotlib.backend_tools.ZoomPanBase(*args)[source]#

Bases:ToolToggleBase

Base class forToolZoom andToolPan.

disable(event=None)[source]#

Release the canvas and disconnect press/release events.

enable(event=None)[source]#

Connect press/release events and lock the canvas.

scroll_zoom(event)[source]#

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

Callsenable ordisable based ontoggled 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 toolsadded.

toolslist, optional

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

matplotlib.backend_tools.add_tools_to_manager(toolmanager,tools={'back':<class'matplotlib.backend_tools.ToolBack'>,'copy':<class'matplotlib.backend_tools.ToolCopyToClipboardBase'>,'cursor':<class'matplotlib.backend_tools.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':<class'matplotlib.backend_tools.ToolHelpBase'>,'home':<class'matplotlib.backend_tools.ToolHome'>,'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':<class'matplotlib.backend_tools.RubberbandBase'>,'save':<class'matplotlib.backend_tools.SaveFigureBase'>,'subplots':<class'matplotlib.backend_tools.ConfigureSubplotsBase'>,'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 aToolManager.

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, seebackend_managers.ToolManager.add_tool for more info.

matplotlib.backend_tools.cursors[source]#

alias ofCursors