### Navigation

- index
- modules |
- next |
- previous |
- home|
- examples|
- tutorials|
- pyplot|
- docs »
- The Matplotlib API »
- backends »

# `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

  `set_figure`(figure)

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

  `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 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

  `set_figure`(figure)

    Assign a figure to the tool

    Parameters: | figure: `Figure`

  `toolmanager`
  `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`

  `set_figure`(figure)

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`(toolmanager, name)

  Bases: `matplotlib.backend_tools._ToolGridBase`

  Tool to toggle the major grids of the figure

  `default_keymap` = [‘g’]
  `description` = ‘Toogle major grids’

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.``ToolMinorGrid`(toolmanager, name)

  Bases: `matplotlib.backend_tools._ToolGridBase`

  Tool to toggle the major and minor grids of the figure

  `default_keymap` = [‘G’]
  `description` = ‘Toogle major and minor grids’

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’, ‘q’]
  `description` = ‘Quit the figure’
  `trigger`(sender, event, data=None)

class `matplotlib.backend_tools.``ToolQuitAll`(toolmanager, name)

  Bases: `matplotlib.backend_tools.ToolBase`

  Tool to call the figure manager destroy method

  `default_keymap` = [‘W’, ‘cmd+W’, ‘Q’]
  `description` = ‘Quit all figures’
  `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

  Parameters: | “*args“ Variable length argument to be used by the Tool “**kwargs“ `toggled` if present and True, sets the initial state ot 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)

    Disable the toggle tool

    `trigger` call this method when `toggled` is True.

    This can happen in different circumstances

    - Click on the toolbar tool button
    - Call to `matplotlib.backend_managers.ToolManager.trigger_tool`
    - Another `ToolToggleBase` derived tool is triggered (from the same `ToolManager`)
  `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

  `set_figure`(figure)
  `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.

  - `ToolZoom`
  - `ToolPan`
  - `ToolHome`
  - `ToolBack`
  - `ToolForward`
  `add_figure`(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`(figure=None)

    Push the current view limits and position onto their respective stacks

  `refresh_locators`()

    Redraw the canvases, update the locators

  `update_home_views`(figure=None)

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

  `update_view`()

    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)

  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={‘xscale’: <class ‘matplotlib.backend_tools.ToolXScale’>, ’position’: <class ‘matplotlib.backend_tools.ToolCursorPosition’>, ’yscale’: <class ‘matplotlib.backend_tools.ToolYScale’>, ’nav’: <class ‘matplotlib.backend_tools.ToolEnableNavigation’>, ’home’: <class ‘matplotlib.backend_tools.ToolHome’>, ’zoom’: <class ‘matplotlib.backend_tools.ToolZoom’>, ’viewpos’: <class ‘matplotlib.backend_tools.ToolViewsPositions’>, ’fullscreen’: <class ‘matplotlib.backend_tools.ToolFullScreen’>, ’quit’: <class ‘matplotlib.backend_tools.ToolQuit’>, ’save’: ‘ToolSaveFigure’, ’rubberband’: ‘ToolRubberband’, ’cursor’: ‘ToolSetCursor’, ’forward’: <class ‘matplotlib.backend_tools.ToolForward’>, ’subplots’: ‘ToolConfigureSubplots’, ’quit_all’: <class ‘matplotlib.backend_tools.ToolQuitAll’>, ’allnav’: <class ‘matplotlib.backend_tools.ToolEnableAllNavigation’>, ’grid’: <class ‘matplotlib.backend_tools.ToolGrid’>, ’grid_minor’: <class ‘matplotlib.backend_tools.ToolMinorGrid’>, ’back’: <class ‘matplotlib.backend_tools.ToolBack’>, ’pan’: <class ‘matplotlib.backend_tools.ToolPan’>})

  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` = {‘xscale’: <class ‘matplotlib.backend_tools.ToolXScale’>, ‘position’: <class ‘matplotlib.backend_tools.ToolCursorPosition’>, ‘yscale’: <class ‘matplotlib.backend_tools.ToolYScale’>, ‘nav’: <class ‘matplotlib.backend_tools.ToolEnableNavigation’>, ‘home’: <class ‘matplotlib.backend_tools.ToolHome’>, ‘zoom’: <class ‘matplotlib.backend_tools.ToolZoom’>, ‘viewpos’: <class ‘matplotlib.backend_tools.ToolViewsPositions’>, ‘fullscreen’: <class ‘matplotlib.backend_tools.ToolFullScreen’>, ‘quit’: <class ‘matplotlib.backend_tools.ToolQuit’>, ‘save’: ‘ToolSaveFigure’, ‘rubberband’: ‘ToolRubberband’, ‘cursor’: ‘ToolSetCursor’, ‘forward’: <class ‘matplotlib.backend_tools.ToolForward’>, ‘subplots’: ‘ToolConfigureSubplots’, ‘quit_all’: <class ‘matplotlib.backend_tools.ToolQuitAll’>, ‘allnav’: <class ‘matplotlib.backend_tools.ToolEnableAllNavigation’>, ‘grid’: <class ‘matplotlib.backend_tools.ToolGrid’>, ‘grid_minor’: <class ‘matplotlib.backend_tools.ToolMinorGrid’>, ‘back’: <class ‘matplotlib.backend_tools.ToolBack’>, ‘pan’: <class ‘matplotlib.backend_tools.ToolPan’>}

  Default tools