### Navigation

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

# `matplotlib.backend_bases`

Abstract base classes define the primitives that renderers and graphics contexts must implement to serve as a matplotlib backend

`RendererBase`
  An abstract base class to handle drawing/rendering operations.
`FigureCanvasBase`
  The abstraction layer that separates the `matplotlib.figure.Figure` from the backend specific details like a user interface drawing area
`GraphicsContextBase`
  An abstract base class that provides color, line styles, etc…
`Event`
  The base class for all of the matplotlib event handling. Derived classes such as `KeyEvent` and `MouseEvent` store the meta data like keys and buttons pressed, x and y locations in pixel and `Axes` coordinates.
`ShowBase`
  The base class for the Show class of each interactive backend; the ‘show’ callable is then set to Show.__call__, inherited from ShowBase.
`ToolContainerBase`
  The base class for the Toolbar class of each interactive backend.
`StatusbarBase`
  The base class for the messaging area.

class `matplotlib.backend_bases.``CloseEvent`(name, canvas, guiEvent=None)

  Bases: `matplotlib.backend_bases.Event`

  An event triggered by a figure being closed

class `matplotlib.backend_bases.``DrawEvent`(name, canvas, renderer)

  Bases: `matplotlib.backend_bases.Event`

  An event triggered by a draw operation on the canvas

  In addition to the `Event` attributes, the following event attributes are defined:

  Attributes

  renderer | (`RendererBase`) the renderer for the draw event

class `matplotlib.backend_bases.``Event`(name, canvas, guiEvent=None)

  Bases: `object`

  A matplotlib event. Attach additional attributes as defined in `FigureCanvasBase.mpl_connect()`. The following attributes are defined and shown with their default values

  Attributes

  name | (str) the event name
  canvas | (`FigureCanvasBase`) the backend-specific canvas instance generating the event
  guiEvent | the GUI event that triggered the matplotlib event

class `matplotlib.backend_bases.``FigureCanvasBase`(figure)

  Bases: `object`

  The canvas the figure renders into.

  Public attributes

  Attributes

  figure | (`matplotlib.figure.Figure`) A high-level figure instance

  `blit`(bbox=None)

    Blit the canvas in bbox (default entire canvas).

  `button_press_event`(x, y, button, dblclick=False, guiEvent=None)

    Backend derived classes should call this function on any mouse button press. x,y are the canvas coords: 0,0 is lower, left. button and key are as defined in `MouseEvent`.

    This method will be call all functions connected to the ‘button_press_event’ with a `MouseEvent` instance.

  `button_release_event`(x, y, button, guiEvent=None)

    Backend derived classes should call this function on any mouse button release.

    This method will call all functions connected to the ‘button_release_event’ with a `MouseEvent` instance.

    Parameters: | x : scalar the canvas coordinates where 0=left y : scalar the canvas coordinates where 0=bottom guiEvent the native UI event that generated the mpl event

  `close_event`(guiEvent=None)

    Pass a `CloseEvent` to all functions connected to `close_event`.

  `draw`(*args, **kwargs)

    Render the `Figure`.

  `draw_cursor`(event)

    Draw a cursor in the event.axes if inaxes is not None. Use native GUI drawing for efficiency if possible

  `draw_event`(renderer)

    Pass a `DrawEvent` to all functions connected to `draw_event`.

  `draw_idle`(*args, **kwargs)

    `draw()` only if idle; defaults to draw but backends can override

  `enter_notify_event`(guiEvent=None, xy=None)

    Backend derived classes should call this function when entering canvas

    Parameters: | guiEvent the native UI event that generated the mpl event xy : tuple of 2 scalars the coordinate location of the pointer when the canvas is entered

  `events` = [‘resize_event’, ‘draw_event’, ‘key_press_event’, ‘key_release_event’, ‘button_press_event’, ‘button_release_event’, ‘scroll_event’, ‘motion_notify_event’, ‘pick_event’, ‘idle_event’, ‘figure_enter_event’, ‘figure_leave_event’, ‘axes_enter_event’, ‘axes_leave_event’, ‘close_event’]
  `filetypes` = {‘pdf’: ‘Portable Document Format’, ‘jpeg’: ‘Joint Photographic Experts Group’, ‘png’: ‘Portable Network Graphics’, ‘raw’: ‘Raw RGBA bitmap’, ‘svgz’: ‘Scalable Vector Graphics’, ‘tif’: ‘Tagged Image File Format’, ‘eps’: ‘Encapsulated Postscript’, ‘ps’: ‘Postscript’, ‘svg’: ‘Scalable Vector Graphics’, ‘rgba’: ‘Raw RGBA bitmap’, ‘tiff’: ‘Tagged Image File Format’, ‘jpg’: ‘Joint Photographic Experts Group’, ‘pgf’: ‘PGF code for LaTeX’}
  `fixed_dpi` = None
  `flush_events`()

    Flush the GUI events for the figure. Implemented only for backends with GUIs.

  `get_default_filename`()

    Return a string, which includes extension, suitable for use as a default filename.

  classmethod `get_default_filetype`()

    Get the default savefig file format as specified in rcParam `savefig.format`. Returned string excludes period. Overridden in backends that only support a single file type.

  classmethod `get_supported_filetypes`()

    Return dict of savefig file formats supported by this backend

  classmethod `get_supported_filetypes_grouped`()

    Return a dict of savefig file formats supported by this backend, where the keys are a file type name, such as ‘Joint Photographic Experts Group’, and the values are a list of filename extensions used for that filetype, such as [‘jpg’, ‘jpeg’].

  `get_width_height`()

    Return the figure width and height in points or pixels (depending on the backend), truncated to integers

  `get_window_title`()

    Get the title text of the window containing the figure. Return None if there is no window (e.g., a PS backend).

  `grab_mouse`(ax)

    Set the child axes which are currently grabbing the mouse events. Usually called by the widgets themselves. It is an error to call this if the mouse is already grabbed by another axes.

  `idle_event`(guiEvent=None)

    Deprecated since version 2.1: The idle_event function was deprecated in version 2.1.

    Called when GUI is idle.

  `is_saving`()

    Returns whether the renderer is in the process of saving to a file, rather than rendering for an on-screen buffer.

  `key_press_event`(key, guiEvent=None)

    Pass a `KeyEvent` to all functions connected to `key_press_event`.

  `key_release_event`(key, guiEvent=None)

    Pass a `KeyEvent` to all functions connected to `key_release_event`.

  `leave_notify_event`(guiEvent=None)

    Backend derived classes should call this function when leaving canvas

    Parameters: | guiEvent the native UI event that generated the mpl event

  `motion_notify_event`(x, y, guiEvent=None)

    Backend derived classes should call this function on any motion-notify-event.

    This method will call all functions connected to the ‘motion_notify_event’ with a `MouseEvent` instance.

    Parameters: | x : scalar the canvas coordinates where 0=left y : scalar the canvas coordinates where 0=bottom guiEvent the native UI event that generated the mpl event

  `mpl_connect`(s, func)

    Connect event with string s to func. The signature of func is:

        def func(event)

    where event is a `matplotlib.backend_bases.Event`. The following events are recognized

    - ‘button_press_event’
    - ‘button_release_event’
    - ‘draw_event’
    - ‘key_press_event’
    - ‘key_release_event’
    - ‘motion_notify_event’
    - ‘pick_event’
    - ‘resize_event’
    - ‘scroll_event’
    - ‘figure_enter_event’,
    - ‘figure_leave_event’,
    - ‘axes_enter_event’,
    - ‘axes_leave_event’
    - ‘close_event’

    For the location events (button and key press/release), if the mouse is over the axes, the variable `event.inaxes` will be set to the `Axes` the event occurs is over, and additionally, the variables `event.xdata` and `event.ydata` will be defined. This is the mouse location in data coords. See `KeyEvent` and `MouseEvent` for more info.

    Return value is a connection id that can be used with `mpl_disconnect()`.

    Examples

    Usage:

        def on_press(event):
            print('you pressed', event.button, event.xdata, event.ydata)

        cid = canvas.mpl_connect('button_press_event', on_press)

  `mpl_disconnect`(cid)

    Disconnect callback id cid

    Examples

    Usage:

        cid = canvas.mpl_connect('button_press_event', on_press)
        #...later
        canvas.mpl_disconnect(cid)

  `new_timer`(*args, **kwargs)

    Creates a new backend-specific subclass of `backend_bases.Timer`. This is useful for getting periodic events through the backend’s native event loop. Implemented only for backends with GUIs.

    Other Parameters:
    | interval : scalar Timer interval in milliseconds callbacks : list Sequence of (func, args, kwargs) where `func(*args, **kwargs)` will be executed by the timer every interval.

  `onRemove`(ev)

    Mouse event processor which removes the top artist under the cursor. Connect this to the ‘mouse_press_event’ using:

        canvas.mpl_connect('mouse_press_event',canvas.onRemove)

  `pick`(mouseevent)
  `pick_event`(mouseevent, artist, **kwargs)

    This method will be called by artists who are picked and will fire off `PickEvent` callbacks registered listeners

  `print_figure`(filename, dpi=None, facecolor=None, edgecolor=None, orientation=’portrait’, format=None, **kwargs)

    Render the figure to hardcopy. Set the figure patch face and edge colors. This is useful because some of the GUIs have a gray figure face color background and you’ll probably want to override this on hardcopy.

    Parameters: | filename can also be a file object on image backends orientation : {‘landscape’, ‘portrait’}, optional only currently applies to PostScript printing. dpi : scalar, optional the dots per inch to save the figure in; if None, use savefig.dpi facecolor : color spec or None, optional the facecolor of the figure; if None, defaults to savefig.facecolor edgecolor : color spec or None, optional the edgecolor of the figure; if None, defaults to savefig.edgecolor format : str, optional when set, forcibly set the file format to save to bbox_inches : str or `Bbox`, optional Bbox in inches. Only the given portion of the figure is saved. If ‘tight’, try to figure out the tight bbox of the figure. If None, use savefig.bbox pad_inches : scalar, optional Amount of padding around the figure when bbox_inches is ‘tight’. If None, use savefig.pad_inches bbox_extra_artists : list of `Artist`, optional A list of extra artists that will be considered when the tight bbox is calculated.

  `release_mouse`(ax)

    Release the mouse grab held by the axes, ax. Usually called by the widgets. It is ok to call this even if you ax doesn’t have the mouse grab currently.

  `resize`(w, h)

    Set the canvas size in pixels.

  `resize_event`()

    Pass a `ResizeEvent` to all functions connected to `resize_event`.

  `scroll_event`(x, y, step, guiEvent=None)

    Backend derived classes should call this function on any scroll wheel event. x,y are the canvas coords: 0,0 is lower, left. button and key are as defined in MouseEvent.

    This method will be call all functions connected to the ‘scroll_event’ with a `MouseEvent` instance.

  `set_window_title`(title)

    Set the title text of the window containing the figure. Note that this has no effect if there is no window (e.g., a PS backend).

  `start_event_loop`(timeout)

    Start an event loop. This is used to start a blocking event loop so that interactive functions, such as ginput and waitforbuttonpress, can wait for events. This should not be confused with the main GUI event loop, which is always running and has nothing to do with this.

    This is implemented only for backends with GUIs.

  `start_event_loop_default`(timeout=0)

    Start an event loop. This is used to start a blocking event loop so that interactive functions, such as ginput and waitforbuttonpress, can wait for events. This should not be confused with the main GUI event loop, which is always running and has nothing to do with this.

    This function provides default event loop functionality based on time.sleep that is meant to be used until event loop functions for each of the GUI backends can be written. As such, it throws a deprecated warning.

    This call blocks until a callback function triggers stop_event_loop() or timeout is reached. If timeout is <=0, never timeout.

  `stop_event_loop`()

    Stop an event loop. This is used to stop a blocking event loop so that interactive functions, such as ginput and waitforbuttonpress, can wait for events.

    This is implemented only for backends with GUIs.

  `stop_event_loop_default`()

    Stop an event loop. This is used to stop a blocking event loop so that interactive functions, such as ginput and waitforbuttonpress, can wait for events.

  `supports_blit` = True
  `switch_backends`(FigureCanvasClass)

    Instantiate an instance of FigureCanvasClass

    This is used for backend switching, e.g., to instantiate a FigureCanvasPS from a FigureCanvasGTK. Note, deep copying is not done, so any changes to one of the instances (e.g., setting figure size or line props), will be reflected in the other

class `matplotlib.backend_bases.``FigureManagerBase`(canvas, num)

  Bases: `object`

  Helper class for pyplot mode, wraps everything up into a neat bundle

  Attributes

  canvas | (`FigureCanvasBase`) The backend-specific canvas instance
  num | (int or str) The figure number

  `destroy`()
  `full_screen_toggle`()
  `get_window_title`()

    Get the title text of the window containing the figure.

    Return None for non-GUI (e.g., PS) backends.

  `key_press`(event)

    Implement the default mpl key bindings defined at Navigation Keyboard Shortcuts

  `resize`(w, h)

    “For GUI backends, resize the window (in pixels).

  `set_window_title`(title)

    Set the title text of the window containing the figure.

    This has no effect for non-GUI (e.g., PS) backends.

  `show`()

    For GUI backends, show the figure window and redraw. For non-GUI backends, raise an exception to be caught by `show()`, for an optional warning.

  `show_popup`(msg)

    Display message in a popup – GUI only.

class `matplotlib.backend_bases.``GraphicsContextBase`

  Bases: `object`

  An abstract base class that provides color, line styles, etc…

  `copy_properties`(gc)

    Copy properties from gc to self

  `get_alpha`()

    Return the alpha value used for blending - not supported on all backends

  `get_antialiased`()

    Return true if the object should try to do antialiased rendering

  `get_capstyle`()

    Return the capstyle as a string in (‘butt’, ‘round’, ‘projecting’)

  `get_clip_path`()

    Return the clip path in the form (path, transform), where path is a `Path` instance, and transform is an affine transform to apply to the path before clipping.

  `get_clip_rectangle`()

    Return the clip rectangle as a `Bbox` instance

  `get_dashes`()

    Return the dash information as an offset dashlist tuple.

    The dash list is a even size list that gives the ink on, ink off in pixels.

    See p107 of to PostScript BLUEBOOK for more info.

    Default value is None

  `get_forced_alpha`()

    Return whether the value given by get_alpha() should be used to override any other alpha-channel values.

  `get_gid`()

    Return the object identifier if one is set, None otherwise.

  `get_hatch`()

    Gets the current hatch style

  `get_hatch_color`()

    Gets the color to use for hatching.

  `get_hatch_linewidth`()

    Gets the linewidth to use for hatching.

  `get_hatch_path`(density=6.0)

    Returns a Path for the current hatch.

  `get_joinstyle`()

    Return the line join style as one of (‘miter’, ‘round’, ‘bevel’)

  `get_linestyle`()

    Deprecated since version 2.1: The get_linestyle function was deprecated in version 2.1.

    Return the linestyle: one of (‘solid’, ‘dashed’, ‘dashdot’, ‘dotted’).

  `get_linewidth`()

    Return the line width in points as a scalar

  `get_rgb`()

    returns a tuple of three or four floats from 0-1.

  `get_sketch_params`()

    Returns the sketch parameters for the artist.

    Returns: | sketch_params : tuple or `None` A 3-tuple with the following elements: `scale`: The amplitude of the wiggle perpendicular to the source line. `length`: The length of the wiggle along the line. `randomness`: The scale factor by which the length is shrunken or expanded. May return `None` if no sketch parameters were set.

  `get_snap`()

    returns the snap setting which may be:

    > - True: snap vertices to the nearest pixel center
    > - False: leave vertices as-is
    > - None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center

  `get_url`()

    returns a url if one is set, None otherwise

  `restore`()

    Restore the graphics context from the stack - needed only for backends that save graphics contexts on a stack

  `set_alpha`(alpha)

    Set the alpha value used for blending - not supported on all backends. If `alpha=None` (the default), the alpha components of the foreground and fill colors will be used to set their respective transparencies (where applicable); otherwise, `alpha` will override them.

  `set_antialiased`(b)

    True if object should be drawn with antialiased rendering

  `set_capstyle`(cs)

    Set the capstyle as a string in (‘butt’, ‘round’, ‘projecting’)

  `set_clip_path`(path)

    Set the clip path and transformation. Path should be a `TransformedPath` instance.

  `set_clip_rectangle`(rectangle)

    Set the clip rectangle with sequence (left, bottom, width, height)

  `set_dashes`(dash_offset, dash_list)

    Set the dash style for the gc.

    Parameters: | dash_offset : float is the offset (usually 0). dash_list : array_like specifies the on-off sequence as points. `(None, None)` specifies a solid line

  `set_foreground`(fg, isRGBA=False)

    Set the foreground color. fg can be a MATLAB format string, a html hex color string, an rgb or rgba unit tuple, or a float between 0 and 1. In the latter case, grayscale is used.

    If you know fg is rgba, set `isRGBA=True` for efficiency.

  `set_gid`(id)

    Sets the id.

  `set_hatch`(hatch)

    Sets the hatch style for filling

  `set_hatch_color`(hatch_color)

    sets the color to use for hatching.

  `set_joinstyle`(js)

    Set the join style to be one of (‘miter’, ‘round’, ‘bevel’)

  `set_linestyle`(style)

    Deprecated since version 2.1: The set_linestyle function was deprecated in version 2.1.

    Set the linestyle to be one of (‘solid’, ‘dashed’, ‘dashdot’, ‘dotted’). These are defined in the rcParams `lines.dashed_pattern`, `lines.dashdot_pattern` and `lines.dotted_pattern`. One may also specify customized dash styles by providing a tuple of (offset, dash pairs).

  `set_linewidth`(w)

    Set the linewidth in points

  `set_sketch_params`(scale=None, length=None, randomness=None)

    Sets the sketch parameters.

    Parameters: | scale : float, optional The amplitude of the wiggle perpendicular to the source line, in pixels. If scale is `None`, or not provided, no sketch filter will be provided. length : float, optional The length of the wiggle along the line, in pixels (default 128) randomness : float, optional The scale factor by which the length is shrunken or expanded (default 16)

  `set_snap`(snap)

    Sets the snap setting which may be:

    > - True: snap vertices to the nearest pixel center
    > - False: leave vertices as-is
    > - None: (auto) If the path contains only rectilinear line segments, round to the nearest pixel center

  `set_url`(url)

    Sets the url for links in compatible backends

class `matplotlib.backend_bases.``IdleEvent`(*args, **kwargs)

  Bases: `matplotlib.backend_bases.Event`

  Deprecated since version 2.1: The IdleEvent class was deprecated in version 2.1.

  An event triggered by the GUI backend when it is idle – useful for passive animation

class `matplotlib.backend_bases.``KeyEvent`(name, canvas, key, x=0, y=0, guiEvent=None)

  Bases: `matplotlib.backend_bases.LocationEvent`

  A key event (key press, key release).

  Attach additional attributes as defined in `FigureCanvasBase.mpl_connect()`.

  In addition to the `Event` and `LocationEvent` attributes, the following attributes are defined:

  Notes

  Modifier keys will be prefixed to the pressed key and will be in the order “ctrl”, “alt”, “super”. The exception to this rule is when the pressed key is itself a modifier key, therefore “ctrl+alt” and “alt+control” can both be valid key values.

  Examples

  Usage:

      def on_key(event):
          print('you pressed', event.key, event.xdata, event.ydata)

      cid = fig.canvas.mpl_connect('key_press_event', on_key)

  Attributes

  key | (None or str) the key(s) pressed. Could be None, a single case sensitive ascii character (“g”, “G”, “#”, etc.), a special key (“control”, “shift”, “f1”, “up”, etc.) or a combination of the above (e.g., “ctrl+alt+g”, “ctrl+alt+G”).

class `matplotlib.backend_bases.``LocationEvent`(name, canvas, x, y, guiEvent=None)

  Bases: `matplotlib.backend_bases.Event`

  An event that has a screen location

  The following additional attributes are defined and shown with their default values.

  In addition to the `Event` attributes, the following event attributes are defined:

  Attributes

  x | (scalar) x position - pixels from left of canvas
  y | (scalar) y position - pixels from bottom of canvas
  inaxes | (bool) the `Axes` instance if mouse is over axes
  xdata | (scalar) x coord of mouse in data coords
  ydata | (scalar) y coord of mouse in data coords

  x, y in figure coords, 0,0 = bottom, left

  `inaxes` = None
  `lastevent` = None
  `x` = None
  `xdata` = None
  `y` = None
  `ydata` = None

class `matplotlib.backend_bases.``MouseEvent`(name, canvas, x, y, button=None, key=None, step=0, dblclick=False, guiEvent=None)

  Bases: `matplotlib.backend_bases.LocationEvent`

  A mouse event (‘button_press_event’,
    ‘button_release_event’, ‘scroll_event’, ‘motion_notify_event’).

  In addition to the `Event` and `LocationEvent` attributes, the following attributes are defined:

  Examples

  Usage:

      def on_press(event):
          print('you pressed', event.button, event.xdata, event.ydata)

      cid = fig.canvas.mpl_connect('button_press_event', on_press)

  Attributes

  button | (None, scalar, or str) button pressed None, 1, 2, 3, ‘up’, ‘down’ (up and down are used for scroll events). Note that in the nbagg backend, both the middle and right clicks return 3 since right clicking will bring up the context menu in some browsers.
  key | (None, or str) the key depressed when the mouse event triggered (see `KeyEvent`)
  step | (scalar) number of scroll steps (positive for ‘up’, negative for ‘down’)

  x, y in figure coords, 0,0 = bottom, left button pressed None, 1, 2, 3, ‘up’, ‘down’

  `button` = None
  `dblclick` = None
  `inaxes` = None
  `step` = None
  `x` = None
  `xdata` = None
  `y` = None
  `ydata` = None

class `matplotlib.backend_bases.``NavigationToolbar2`(canvas)

  Bases: `object`

  Base class for the navigation cursor, version 2

  backends must implement a canvas that handles connections for ‘button_press_event’ and ‘button_release_event’. See `FigureCanvasBase.mpl_connect()` for more information

  They must also define

  > `save_figure()`
  >   save the current figure
  > `set_cursor()`
  >   if you want the pointer icon to change
  > `_init_toolbar()`
  >   create your toolbar widget
  > `draw_rubberband()` (optional)
  >   draw the zoom to rect “rubberband” rectangle
  > `press()` (optional)
  >   whenever a mouse button is pressed, you’ll be notified with the event
  > `release()` (optional)
  >   whenever a mouse button is released, you’ll be notified with the event
  > `set_message()` (optional)
  >   display message
  > `set_history_buttons()` (optional)
  >   you can change the history back / forward buttons to indicate disabled / enabled state.

  That’s it, we’ll do the rest!

  `back`(*args)

    move back up the view lim stack

  `drag_pan`(event)

    Callback for dragging in pan/zoom mode.

  `drag_zoom`(event)

    Callback for dragging in zoom mode.

  `draw`()

    Redraw the canvases, update the locators.

  `draw_rubberband`(event, x0, y0, x1, y1)

    Draw a rectangle rubberband to indicate zoom limits.

    Note that it is not guaranteed that `x0 <= x1` and `y0 <= y1`.

  `dynamic_update`()

    Deprecated since version 2.1: The dynamic_update function was deprecated in version 2.1. Use canvas.draw_idle instead.

  `forward`(*args)

    Move forward in the view lim stack.

  `home`(*args)

    Restore the original view.

  `mouse_move`(event)
  `pan`(*args)

    Activate the pan/zoom tool. pan with left button, zoom with right

  `press`(event)

    Called whenver a mouse button is pressed.

  `press_pan`(event)

    Callback for mouse button press in pan/zoom mode.

  `press_zoom`(event)

    Callback for mouse button press in zoom to rect mode.

  `push_current`()

    Push the current view limits and position onto the stack.

  `release`(event)

    Callback for mouse button release.

  `release_pan`(event)

    Callback for mouse button release in pan/zoom mode.

  `release_zoom`(event)

    Callback for mouse button release in zoom to rect mode.

  `remove_rubberband`()

    Remove the rubberband.

  `save_figure`(*args)

    Save the current figure.

  `set_cursor`(cursor)

    Set the current cursor to one of the `Cursors` enums values.

  `set_history_buttons`()

    Enable or disable the back/forward button.

  `set_message`(s)

    Display a message on toolbar or in status bar.

  `toolitems` = ((‘Home’, ‘Reset original view’, ‘home’, ‘home’), (‘Back’, ‘Back to previous view’, ‘back’, ‘back’), (‘Forward’, ‘Forward to next view’, ‘forward’, ‘forward’), (None, None, None, None), (‘Pan’, ‘Pan axes with left mouse, zoom with right’, ‘move’, ‘pan’), (‘Zoom’, ‘Zoom to rectangle’, ‘zoom_to_rect’, ‘zoom’), (‘Subplots’, ‘Configure subplots’, ‘subplots’, ‘configure_subplots’), (None, None, None, None), (‘Save’, ‘Save the figure’, ‘filesave’, ‘save_figure’))
  `update`()

    Reset the axes stack.

  `zoom`(*args)

    Activate zoom to rect mode.

exception `matplotlib.backend_bases.``NonGuiException`

  Bases: `Exception`

class `matplotlib.backend_bases.``PickEvent`(name, canvas, mouseevent, artist, guiEvent=None, **kwargs)

  Bases: `matplotlib.backend_bases.Event`

  a pick event, fired when the user picks a location on the canvas sufficiently close to an artist.

  Attrs: all the `Event` attributes plus

  Examples

  Usage:

      ax.plot(np.rand(100), 'o', picker=5)  # 5 points tolerance

      def on_pick(event):
          line = event.artist
          xdata, ydata = line.get_data()
          ind = event.ind
          print('on pick line:', np.array([xdata[ind], ydata[ind]]).T)

      cid = fig.canvas.mpl_connect('pick_event', on_pick)

  Attributes

  mouseevent | (`MouseEvent`) the mouse event that generated the pick
  artist | (`matplotlib.artist.Artist`) the picked artist
  other | extra class dependent attrs – e.g., a `Line2D` pick may define different extra attributes than a `PatchCollection` pick event

class `matplotlib.backend_bases.``RendererBase`

  Bases: `object`

  An abstract base class to handle drawing/rendering operations.

  The following methods must be implemented in the backend for full functionality (though just implementing `draw_path()` alone would give a highly capable backend):

  - `draw_path()`
  - `draw_image()`
  - `draw_gouraud_triangle()`

  The following methods should be implemented in the backend for optimization reasons:

  - `draw_text()`
  - `draw_markers()`
  - `draw_path_collection()`
  - `draw_quad_mesh()`
  `close_group`(s)

    Close a grouping element with label s Is only currently used by `backend_svg`

  `draw_gouraud_triangle`(gc, points, colors, transform)

    Draw a Gouraud-shaded triangle.

    Parameters: | points : array_like, shape=(3, 2) Array of (x, y) points for the triangle. colors : array_like, shape=(3, 4) RGBA colors for each point of the triangle. transform : `matplotlib.transforms.Transform` An affine transform to apply to the points.

  `draw_gouraud_triangles`(gc, triangles_array, colors_array, transform)

    Draws a series of Gouraud triangles.

    Parameters: | points : array_like, shape=(N, 3, 2) Array of N (x, y) points for the triangles. colors : array_like, shape=(N, 3, 4) Array of N RGBA colors for each point of the triangles. transform : `matplotlib.transforms.Transform` An affine transform to apply to the points.

  `draw_image`(gc, x, y, im, transform=None)

    Draw an RGBA image.

    Parameters: | gc : `GraphicsContextBase` a graphics context with clipping information. x : scalar the distance in physical units (i.e., dots or pixels) from the left hand side of the canvas. y : scalar the distance in physical units (i.e., dots or pixels) from the bottom side of the canvas. im : array_like, shape=(N, M, 4), dtype=np.uint8 An array of RGBA pixels. transform : `matplotlib.transforms.Affine2DBase` If and only if the concrete backend is written such that `option_scale_image()` returns `True`, an affine transformation may be passed to `draw_image()`. It takes the form of a `Affine2DBase` instance. The translation vector of the transformation is given in physical units (i.e., dots or pixels). Note that the transformation does not override `x` and `y`, and has to be applied before translating the result by `x` and `y` (this can be accomplished by adding `x` and `y` to the translation vector defined by `transform`).

  `draw_markers`(gc, marker_path, marker_trans, path, trans, rgbFace=None)

    Draws a marker at each of the vertices in path. This includes all vertices, including control points on curves. To avoid that behavior, those vertices should be removed before calling this function.

    This provides a fallback implementation of draw_markers that makes multiple calls to `draw_path()`. Some backends may want to override this method in order to draw the marker only once and reuse it multiple times.

    Parameters: | gc : `GraphicsContextBase` The graphics context marker_trans : `matplotlib.transforms.Transform` An affine transform applied to the marker. trans : `matplotlib.transforms.Transform` An affine transform applied to the path.

  `draw_path`(gc, path, transform, rgbFace=None)

    Draws a `Path` instance using the given affine transform.

  `draw_path_collection`(gc, master_transform, paths, all_transforms, offsets, offsetTrans, facecolors, edgecolors, linewidths, linestyles, antialiaseds, urls, offset_position)

    Draws a collection of paths selecting drawing properties from the lists facecolors, edgecolors, linewidths, linestyles and antialiaseds. offsets is a list of offsets to apply to each of the paths. The offsets in offsets are first transformed by offsetTrans before being applied. offset_position may be either “screen” or “data” depending on the space that the offsets are in.

    This provides a fallback implementation of `draw_path_collection()` that makes multiple calls to `draw_path()`. Some backends may want to override this in order to render each set of path data only once, and then reference that path multiple times with the different offsets, colors, styles etc. The generator methods `_iter_collection_raw_paths()` and `_iter_collection()` are provided to help with (and standardize) the implementation across backends. It is highly recommended to use those generators, so that changes to the behavior of `draw_path_collection()` can be made globally.

  `draw_quad_mesh`(gc, master_transform, meshWidth, meshHeight, coordinates, offsets, offsetTrans, facecolors, antialiased, edgecolors)

    This provides a fallback implementation of `draw_quad_mesh()` that generates paths and then calls `draw_path_collection()`.

  `draw_tex`(gc, x, y, s, prop, angle, ismath=’TeX!’, mtext=None)
  `draw_text`(gc, x, y, s, prop, angle, ismath=False, mtext=None)

    Draw the text instance

    Parameters: | gc : `GraphicsContextBase` the graphics context x : scalar the x location of the text in display coords y : scalar the y location of the text baseline in display coords s : str the text string prop : `matplotlib.font_manager.FontProperties` font properties angle : scalar the rotation angle in degrees mtext : `matplotlib.text.Text` the original text object to be rendered

    Notes

    backend implementers note

    When you are trying to determine if you have gotten your bounding box right (which is what enables the text layout/alignment to work properly), it helps to change the line in text.py:

        if 0: bbox_artist(self, renderer)

    to if 1, and then the actual bounding box will be plotted along with your text.

  `flipy`()

    Return true if y small numbers are top for renderer Is used for drawing text (`matplotlib.text`) and images (`matplotlib.image`) only

  `get_canvas_width_height`()

    return the canvas width and height in display coords

  `get_image_magnification`()

    Get the factor by which to magnify images passed to `draw_image()`. Allows a backend to have images at a different resolution to other artists.

  `get_texmanager`()

    return the `matplotlib.texmanager.TexManager` instance

  `get_text_width_height_descent`(s, prop, ismath)

    Get the width, height, and descent (offset from the bottom to the baseline), in display coords, of the string s with `FontProperties` prop

  `new_gc`()

    Return an instance of a `GraphicsContextBase`

  `open_group`(s, gid=None)

    Open a grouping element with label s. If gid is given, use gid as the id of the group. Is only currently used by `backend_svg`.

  `option_image_nocomposite`()

    override this method for renderers that do not necessarily always want to rescale and composite raster images. (like SVG, PDF, or PS)

  `option_scale_image`()

    override this method for renderers that support arbitrary affine transformations in `draw_image()` (most vector backends).

  `points_to_pixels`(points)

    Convert points to display units

    You need to override this function (unless your backend doesn’t have a dpi, e.g., postscript or svg). Some imaging systems assume some value for pixels per inch:

        points to pixels = points * pixels_per_inch/72.0 * dpi/72.0

    Parameters: | points : scalar or array_like a float or a numpy array of float
    Returns: | Points converted to pixels

  `start_filter`()

    Used in AggRenderer. Switch to a temporary renderer for image filtering effects.

  `start_rasterizing`()

    Used in MixedModeRenderer. Switch to the raster renderer.

  `stop_filter`(filter_func)

    Used in AggRenderer. Switch back to the original renderer. The contents of the temporary renderer is processed with the filter_func and is drawn on the original renderer as an image.

  `stop_rasterizing`()

    Used in MixedModeRenderer. Switch back to the vector renderer and draw the contents of the raster renderer as an image on the vector renderer.

  `strip_math`(s)

class `matplotlib.backend_bases.``ResizeEvent`(name, canvas)

  Bases: `matplotlib.backend_bases.Event`

  An event triggered by a canvas resize

  In addition to the `Event` attributes, the following event attributes are defined:

  Attributes

  width | (scalar) width of the canvas in pixels
  height | (scalar) height of the canvas in pixels

class `matplotlib.backend_bases.``ShowBase`

  Bases: `object`

  Simple base class to generate a show() callable in backends.

  Subclass must override mainloop() method.

  `mainloop`()

class `matplotlib.backend_bases.``StatusbarBase`(toolmanager)

  Bases: `object`

  Base class for the statusbar

  `set_message`(s)

    Display a message on toolbar or in status bar

    Parameters: | s : str Message text

class `matplotlib.backend_bases.``TimerBase`(interval=None, callbacks=None)

  Bases: `object`

  A base class for providing timer events, useful for things animations. Backends need to implement a few specific methods in order to use their own timing mechanisms so that the timer events are integrated into their event loops.

  Mandatory functions that must be implemented:

  > - `_timer_start`: Contains backend-specific code for starting the timer
  > - `_timer_stop`: Contains backend-specific code for stopping the timer

  Optional overrides:

  > - `_timer_set_single_shot`: Code for setting the timer to single shot operating mode, if supported by the timer object. If not, the `Timer` class itself will store the flag and the `_on_timer` method should be overridden to support such behavior.
  > - `_timer_set_interval`: Code for setting the interval on the timer, if there is a method for doing so on the timer object.
  > - `_on_timer`: This is the internal function that any timer object should call, which will handle the task of running all callbacks that have been set.

  Attributes

  interval | (scalar) The time between timer events in milliseconds. Default is 1000 ms.
  single_shot | (bool) Boolean flag indicating whether this timer should operate as single shot (run once and then stop). Defaults to `False`.
  callbacks | (list) Stores list of (func, args) tuples that will be called upon timer events. This list can be manipulated directly, or the functions `add_callback` and `remove_callback` can be used.

  `add_callback`(func, *args, **kwargs)

    Register `func` to be called by timer when the event fires. Any additional arguments provided will be passed to `func`.

  `interval`
  `remove_callback`(func, *args, **kwargs)

    Remove `func` from list of callbacks. `args` and `kwargs` are optional and used to distinguish between copies of the same function registered to be called with different arguments.

  `single_shot`
  `start`(interval=None)

    Start the timer object. `interval` is optional and will be used to reset the timer interval first if provided.

  `stop`()

    Stop the timer.

class `matplotlib.backend_bases.``ToolContainerBase`(toolmanager)

  Bases: `object`

  Base class for all tool containers, e.g. toolbars.

  Attributes

  toolmanager | (`ToolManager`) The tools with which this `ToolContainer` wants to communicate.

  `add_tool`(tool, group, position=-1)

    Adds a tool to this container

    Parameters: | tool : tool_like The tool to add, see `ToolManager.get_tool`. group : str The name of the group to add this tool to. position : int (optional) The position within the group to place this tool. Defaults to end.

  `add_toolitem`(name, group, position, image, description, toggle)

    Add a toolitem to the container

    This method must get implemented per backend

    The callback associated with the button click event, must be EXACTLY `self.trigger_tool(name)`

    Parameters: | name : string Name of the tool to add, this gets used as the tool’s ID and as the default label of the buttons group : String Name of the group that this tool belongs to position : Int Position of the tool within its group, if -1 it goes at the End image_file : String Filename of the image for the button or `None` description : String Description of the tool, used for the tooltips toggle : Bool `True` : The button is a toggle (change the pressed/unpressed state between consecutive clicks) `False` : The button is a normal button (returns to unpressed state after release)

  `remove_toolitem`(name)

    Remove a toolitem from the `ToolContainer`

    This method must get implemented per backend

    Called when `ToolManager` emits a `tool_removed_event`

    Parameters: | name : string Name of the tool to remove

  `toggle_toolitem`(name, toggled)

    Toggle the toolitem without firing event

    Parameters: | name : String Id of the tool to toggle toggled : bool Whether to set this tool as toggled or not.

  `trigger_tool`(name)

    Trigger the tool

    Parameters: | name : String Name (id) of the tool triggered from within the container

`matplotlib.backend_bases.``get_registered_canvas_class`(format)

  Return the registered default canvas for given file format. Handles deferred import of required backend.

`matplotlib.backend_bases.``key_press_handler`(event, canvas, toolbar=None)

  Implement the default mpl key bindings for the canvas and toolbar described at Navigation Keyboard Shortcuts

  Parameters: | event : `KeyEvent` a key press/release event canvas : `FigureCanvasBase` the backend-specific canvas instance toolbar : `NavigationToolbar2` the navigation cursor toolbar

`matplotlib.backend_bases.``register_backend`(format, backend, description=None)

  Register a backend for saving to a given file format.

  Parameters: | format : str File extension backend : module string or canvas class Backend for handling file output description : str, optional Description of the file type. Defaults to an empty string