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) [source]

Bases: matplotlib.backend_bases.Event

An event triggered by a figure being closed.

class matplotlib.backend_bases.DrawEvent(name, canvas, renderer) [source]

Bases: matplotlib.backend_bases.Event

An event triggered by a draw operation on the canvas

In most backends callbacks subscribed to this callback will be fired after the rendering is complete but before the screen is updated. Any extra artists drawn to the canvas's renderer will be reflected without an explicit call to blit.

Warning

Calling canvas.draw and canvas.blit in these callbacks may not be safe with all backends and may cause infinite recursion.

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

Attributes:	rendererRendererBase the renderer for the draw event

class matplotlib.backend_bases.Event(name, canvas, guiEvent=None) [source]

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:	namestr the event name canvasFigureCanvasBase the backend-specific canvas instance generating the event guiEvent the GUI event that triggered the matplotlib event

class matplotlib.backend_bases.FigureCanvasBase(figure) [source]

Bases: object

The canvas the figure renders into.

Public attributes

Attributes:	figurematplotlib.figure.Figure A high-level figure instance

blit(self, bbox=None) [source]

Blit the canvas in bbox (default entire canvas).

button_press_event(self, x, y, button, dblclick=False, guiEvent=None) [source]

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(self, x, y, button, guiEvent=None) [source]

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:	xfloat The canvas coordinates where 0=left. yfloat The canvas coordinates where 0=bottom. guiEvent The native UI event that generated the Matplotlib event.

close_event(self, guiEvent=None) [source]

Pass a CloseEvent to all functions connected to close_event.

draw(self, *args, **kwargs) [source]

Render the Figure.

draw_cursor(self, event) [source]

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

Notes

Deprecated since version 3.2.

draw_event(self, renderer) [source]

Pass a DrawEvent to all functions connected to draw_event.

draw_idle(self, *args, **kwargs) [source]

Request a widget redraw once control returns to the GUI event loop.

Even if multiple calls to draw_idle occur before control returns to the GUI event loop, the figure will only be rendered once.

Notes

Backends may choose to override the method and implement their own strategy to prevent multiple renderings.

enter_notify_event(self, guiEvent=None, xy=None) [source]

Backend derived classes should call this function when entering canvas

Parameters:	guiEvent The native UI event that generated the Matplotlib event. xy(float, float) 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 = {'eps': 'Encapsulated Postscript', 'jpeg': 'Joint Photographic Experts Group', 'jpg': 'Joint Photographic Experts Group', 'pdf': 'Portable Document Format', 'pgf': 'PGF code for LaTeX', 'png': 'Portable Network Graphics', 'ps': 'Postscript', 'raw': 'Raw RGBA bitmap', 'rgba': 'Raw RGBA bitmap', 'svg': 'Scalable Vector Graphics', 'svgz': 'Scalable Vector Graphics', 'tif': 'Tagged Image File Format', 'tiff': 'Tagged Image File Format'}

fixed_dpi = None

flush_events(self) [source]

Flush the GUI events for the figure.

Interactive backends need to reimplement this method.

get_default_filename(self) [source]

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

classmethod get_default_filetype() [source]

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() [source]

Return dict of savefig file formats supported by this backend.

classmethod get_supported_filetypes_grouped() [source]

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(self) [source]

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

get_window_title(self) [source]

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

grab_mouse(self, ax) [source]

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.

inaxes(self, xy) [source]

Return the topmost visible Axes containing the point xy.

Parameters:	xytuple or list (x, y) coordinates. x position - pixels from left of canvas. y position - pixels from bottom of canvas.
Returns:	axesAxes or None The topmost visible axes containing the point, or None if no axes.

is_saving(self) [source]

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

key_press_event(self, key, guiEvent=None) [source]

Pass a KeyEvent to all functions connected to key_press_event.

key_release_event(self, key, guiEvent=None) [source]

Pass a KeyEvent to all functions connected to key_release_event.

leave_notify_event(self, guiEvent=None) [source]

Backend derived classes should call this function when leaving canvas

Parameters:	guiEvent The native UI event that generated the Matplotlib event.

motion_notify_event(self, x, y, guiEvent=None) [source]

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:	xfloat The canvas coordinates where 0=left. yfloat The canvas coordinates where 0=bottom. guiEvent The native UI event that generated the Matplotlib event.

mpl_connect(self, s, func) [source]

Bind function func to event s.

Parameters:

sstr One of the following events ids: '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'. funccallable The callback function to be executed, which must have the signature: def func(event: Event) -> Any For the location events (button and key press/release), if the mouse is over the axes, the inaxes attribute of the event will be set to the Axes the event occurs is over, and additionally, the variables xdata and ydata attributes will be set to the mouse location in data coordinates. See KeyEvent and MouseEvent for more info.

Returns:

cid A connection id that can be used with FigureCanvasBase.mpl_disconnect.

Examples

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

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

mpl_disconnect(self, cid) [source]

Disconnect the callback with id cid.

Examples

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

new_timer(self, *args, **kwargs) [source]

Create a new backend-specific subclass of Timer.

This is useful for getting periodic events through the backend's native event loop. Implemented only for backends with GUIs.

Other Parameters:	intervalscalar Timer interval in milliseconds callbacksList[Tuple[callable, Tuple, Dict]] Sequence of (func, args, kwargs) where func(*args, **kwargs) will be executed by the timer every interval. Callbacks which return False or 0 will be removed from the timer.

Examples

>>> timer = fig.canvas.new_timer(callbacks=[(f1, (1, ), {'a': 3}),])

pick(self, mouseevent) [source]

pick_event(self, mouseevent, artist, **kwargs) [source]

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

print_figure(self, filename, dpi=None, facecolor=None, edgecolor=None, orientation='portrait', format=None, *, bbox_inches=None, **kwargs) [source]

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'}, default: 'portrait' only currently applies to PostScript printing. dpiscalar, optional the dots per inch to save the figure in; if None, use savefig.dpi facecolorcolor, default: rcParams["savefig.facecolor"] (default: 'white') The facecolor of the figure. edgecolorcolor, default: rcParams["savefig.edgecolor"] (default: 'white') The edgecolor of the figure. formatstr, optional Force a specific file format. If not given, the format is inferred from the filename extension, and if that fails from rcParams["savefig.format"] (default: 'png'). bbox_inches'tight' or Bbox, default: rcParams["savefig.bbox"] (default: None) Bbox in inches. Only the given portion of the figure is saved. If 'tight', try to figure out the tight bbox of the figure. pad_inchesfloat, default: rcParams["savefig.pad_inches"] (default: 0.1) Amount of padding around the figure when bbox_inches is 'tight'. bbox_extra_artistslist of Artist, optional A list of extra artists that will be considered when the tight bbox is calculated.

release_mouse(self, ax) [source]

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.

required_interactive_framework = None

resize(self, w, h) [source]

Set the canvas size in pixels.

resize_event(self) [source]

Pass a ResizeEvent to all functions connected to resize_event.

scroll_event(self, x, y, step, guiEvent=None) [source]

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(self, title) [source]

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(self, timeout=0) [source]

Start a blocking event loop.

Such an event loop is used by interactive functions, such as ginput and waitforbuttonpress, to wait for events.

The event loop blocks until a callback function triggers stop_event_loop, or timeout is reached.

If timeout is 0 or negative, never timeout.

Only interactive backends need to reimplement this method and it relies on flush_events being properly implemented.

Interactive backends should implement this in a more native way.

stop_event_loop(self) [source]

Stop the current blocking event loop.

Interactive backends need to reimplement this to match start_event_loop

supports_blit = False

switch_backends(self, FigureCanvasClass) [source]

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) [source]

Bases: object

A backend-independent abstraction of a figure container and controller.

The figure manager is used by pyplot to interact with the window in a backend-independent way. It's an adapter for the real (GUI) framework that represents the visual figure on screen.

GUI backends define from this class to translate common operations such as show or resize to the GUI-specific code. Non-GUI backends do not support these operations an can just use the base class.

This following basic operations are accessible:

Window operations

• show
• destroy
• full_screen_toggle
• resize
• get_window_title
• set_window_title

Key and mouse button press handling

The figure manager sets up default key and mouse button press handling by hooking up the key_press_handler to the matplotlib event system. This ensures the same shortcuts and mouse actions across backends.

Other operations

Subclasses will have additional attributes and functions to access additional functionality. This is of course backend-specific. For example, most GUI backends have window and toolbar attributes that give access to the native GUI widgets of the respective framework.

Attributes:

canvasFigureCanvasBase The backend-specific canvas instance. numint or str The figure number. key_press_handler_idint The default key handler cid, when using the toolmanager. To disable the default key press handling use: figure.canvas.mpl_disconnect( figure.canvas.manager.key_press_handler_id) button_press_handler_idint The default mouse button handler cid, when using the toolmanager. To disable the default button press handling use: figure.canvas.mpl_disconnect( figure.canvas.manager.button_press_handler_id)

button_press(self, event) [source]

The default Matplotlib button actions for extra mouse buttons.

destroy(self) [source]

full_screen_toggle(self) [source]

get_window_title(self) [source]

Get the title text of the window containing the figure.

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

key_press(self, event) [source]

Implement the default Matplotlib key bindings defined at Navigation Keyboard Shortcuts.

resize(self, w, h) [source]

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

set_window_title(self, title) [source]

Set the title text of the window containing the figure.

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

show(self) [source]

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.

class matplotlib.backend_bases.GraphicsContextBase [source]

Bases: object

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

copy_properties(self, gc) [source]

Copy properties from gc to self

get_alpha(self) [source]

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

get_antialiased(self) [source]

Return whether the object should try to do antialiased rendering.

get_capstyle(self) [source]

Return the capstyle as a string in ('butt', 'round', 'projecting').

get_clip_path(self) [source]

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(self) [source]

Return the clip rectangle as a Bbox instance.

get_dashes(self) [source]

Return the dash style as an (offset, dash-list) pair.

The dash list is a even-length list that gives the ink on, ink off in points. See p. 107 of to PostScript blue book for more info.

Default value is (None, None).

get_forced_alpha(self) [source]

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

get_gid(self) [source]

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

get_hatch(self) [source]

Get the current hatch style.

get_hatch_color(self) [source]

Get the hatch color.

get_hatch_linewidth(self) [source]

Get the hatch linewidth.

get_hatch_path(self, density=6.0) [source]

Return a Path for the current hatch.

get_joinstyle(self) [source]

Return the line join style as one of ('miter', 'round', 'bevel').

get_linewidth(self) [source]

Return the line width in points.

get_rgb(self) [source]

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

get_sketch_params(self) [source]

Return the sketch parameters for the artist.

Returns:	sketch_paramstuple 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(self) [source]

Returns the snap setting, which can 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(self) [source]

Return a url if one is set, None otherwise.

restore(self) [source]

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

set_alpha(self, alpha) [source]

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(self, b) [source]

Set whether object should be drawn with antialiased rendering.

set_capstyle(self, cs) [source]

Set the capstyle to be one of ('butt', 'round', 'projecting').

set_clip_path(self, path) [source]

Set the clip path and transformation.

Parameters:	pathTransformedPath or None

set_clip_rectangle(self, rectangle) [source]

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

set_dashes(self, dash_offset, dash_list) [source]

Set the dash style for the gc.

Parameters:	dash_offsetfloat or None The offset (usually 0). dash_listarray-like or None The on-off sequence as points.

Notes

(None, None) specifies a solid line.

See p. 107 of to PostScript blue book for more info.

set_foreground(self, fg, isRGBA=False) [source]

Set the foreground color.

Parameters:	fgcolor isRGBAbool If fg is known to be an (r, g, b, a) tuple, isRGBA can be set to True to improve performance.

set_gid(self, id) [source]

Set the id.

set_hatch(self, hatch) [source]

Set the hatch style (for fills).

set_hatch_color(self, hatch_color) [source]

Set the hatch color.

set_joinstyle(self, js) [source]

Set the join style to be one of ('miter', 'round', 'bevel').

set_linewidth(self, w) [source]

Set the linewidth in points.

set_sketch_params(self, scale=None, length=None, randomness=None) [source]

Set the sketch parameters.

Parameters:	scalefloat, 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. lengthfloat, default: 128 The length of the wiggle along the line, in pixels. randomnessfloat, default: 16 The scale factor by which the length is shrunken or expanded.

set_snap(self, snap) [source]

Set 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(self, url) [source]

Set the url for links in compatible backends.

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

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

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

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

Attributes:	keyNone 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").

(x, y) in figure coords ((0, 0) = bottom left).

class matplotlib.backend_bases.LocationEvent(name, canvas, x, y, guiEvent=None) [source]

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:	xint x position - pixels from left of canvas. yint y position - pixels from bottom of canvas. inaxesAxes or None The Axes instance over which the mouse is, if any. xdatafloat or None x data coordinate of the mouse. ydatafloat or None y data coordinate of the mouse.

(x, y) in figure coords ((0, 0) = bottom left).

lastevent = None

class matplotlib.backend_bases.MouseButton(value) [source]

Bases: enum.IntEnum

An enumeration.

BACK = 8

FORWARD = 9

LEFT = 1

MIDDLE = 2

RIGHT = 3

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

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

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, MouseButton.LEFT, MouseButton.MIDDLE, MouseButton.RIGHT, 'up', 'down'} The button pressed. 'up' and 'down' are used for scroll events. Note that in the nbagg backend, both the middle and right clicks return RIGHT since right clicking will bring up the context menu in some browsers. Note that LEFT and RIGHT actually refer to the "primary" and "secondary" buttons, i.e. if the user inverts their left and right buttons ("left-handed setting") then the LEFT button will be the one physically on the right. keyNone or str The key pressed when the mouse event triggered, e.g. 'shift'. See KeyEvent. stepint The number of scroll steps (positive for 'up', negative for 'down'). This applies only to 'scroll_event' and defaults to 0 otherwise. dblclickbool Whether the event is a double-click. This applies only to 'button_press_event' and is False otherwise. In particular, it's not used in 'button_release_event'.

(x, y) in figure coords ((0, 0) = bottom left) button pressed None, 1, 2, 3, 'up', 'down'

class matplotlib.backend_bases.NavigationToolbar2(canvas) [source]

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(self, *args) [source]

Move back up the view lim stack.

drag_pan(self, event) [source]

Callback for dragging in pan/zoom mode.

drag_zoom(self, event) [source]

Callback for dragging in zoom mode.

draw(self) [source]

Redraw the canvases, update the locators.

draw_rubberband(self, event, x0, y0, x1, y1) [source]

Draw a rectangle rubberband to indicate zoom limits.

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

forward(self, *args) [source]

Move forward in the view lim stack.

home(self, *args) [source]

Restore the original view.

mouse_move(self, event) [source]

pan(self, *args) [source]

Activate the pan/zoom tool.

Pan with left button, zoom with right.

press(self, event) [source]

Called whenever a mouse button is pressed.

press_pan(self, event) [source]

Callback for mouse button press in pan/zoom mode.

press_zoom(self, event) [source]

Callback for mouse button press in zoom to rect mode.

push_current(self) [source]

Push the current view limits and position onto the stack.

release(self, event) [source]

Callback for mouse button release.

release_pan(self, event) [source]

Callback for mouse button release in pan/zoom mode.

release_zoom(self, event) [source]

Callback for mouse button release in zoom to rect mode.

remove_rubberband(self) [source]

Remove the rubberband.

save_figure(self, *args) [source]

Save the current figure.

set_cursor(self, cursor) [source]

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

If required by the backend, this method should trigger an update in the backend event loop after the cursor is set, as this method may be called e.g. before a long-running task during which the GUI is not updated.

set_history_buttons(self) [source]

Enable or disable the back/forward button.

set_message(self, s) [source]

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(self) [source]

Reset the axes stack.

zoom(self, *args) [source]

Activate zoom to rect mode.

exception matplotlib.backend_bases.NonGuiException [source]

Bases: Exception

Raised when trying show a figure in a non-GUI backend.

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

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

::

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:	mouseeventMouseEvent the mouse event that generated the pick artistmatplotlib.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 [source]

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(self, s) [source]

Close a grouping element with label s.

Only used by the SVG renderer.

draw_gouraud_triangle(self, gc, points, colors, transform) [source]

Draw a Gouraud-shaded triangle.

Parameters:	pointsarray-like, shape=(3, 2) Array of (x, y) points for the triangle. colorsarray-like, shape=(3, 4) RGBA colors for each point of the triangle. transformmatplotlib.transforms.Transform An affine transform to apply to the points.

draw_gouraud_triangles(self, gc, triangles_array, colors_array, transform) [source]

Draw a series of Gouraud triangles.

Parameters:	pointsarray-like, shape=(N, 3, 2) Array of N (x, y) points for the triangles. colorsarray-like, shape=(N, 3, 4) Array of N RGBA colors for each point of the triangles. transformmatplotlib.transforms.Transform An affine transform to apply to the points.

draw_image(self, gc, x, y, im, transform=None) [source]

Draw an RGBA image.

Parameters:

gcGraphicsContextBase A graphics context with clipping information. xscalar The distance in physical units (i.e., dots or pixels) from the left hand side of the canvas. yscalar The distance in physical units (i.e., dots or pixels) from the bottom side of the canvas. imarray-like, shape=(N, M, 4), dtype=np.uint8 An array of RGBA pixels. transformmatplotlib.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(self, gc, marker_path, marker_trans, path, trans, rgbFace=None) [source]

Draw 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:	gcGraphicsContextBase The graphics context. marker_transmatplotlib.transforms.Transform An affine transform applied to the marker. transmatplotlib.transforms.Transform An affine transform applied to the path.

draw_path(self, gc, path, transform, rgbFace=None) [source]

Draw a Path instance using the given affine transform.

draw_path_collection(self, gc, master_transform, paths, all_transforms, offsets, offsetTrans, facecolors, edgecolors, linewidths, linestyles, antialiaseds, urls, offset_position) [source]

Draw 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(self, gc, master_transform, meshWidth, meshHeight, coordinates, offsets, offsetTrans, facecolors, antialiased, edgecolors) [source]

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

draw_tex(self, gc, x, y, s, prop, angle, ismath='TeX!', mtext=None) [source]

draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None) [source]

Draw the text instance.

Parameters:	gcGraphicsContextBase The graphics context. xfloat The x location of the text in display coords. yfloat The y location of the text baseline in display coords. sstr The text string. propmatplotlib.font_manager.FontProperties The font properties. anglefloat The rotation angle in degrees anti-clockwise. mtextmatplotlib.text.Text The original text object to be rendered.

Notes

Note for backend implementers:

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(self) [source]

Return whether y values increase from top to bottom.

Note that this only affects drawing of texts and images.

get_canvas_width_height(self) [source]

Return the canvas width and height in display coords.

get_image_magnification(self) [source]

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(self) [source]

Return the TexManager instance.

get_text_width_height_descent(self, s, prop, ismath) [source]

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(self) [source]

Return an instance of a GraphicsContextBase.

open_group(self, s, gid=None) [source]

Open a grouping element with label s and gid (if set) as id.

Only used by the SVG renderer.

option_image_nocomposite(self) [source]

Return whether image composition by Matplotlib should be skipped.

Raster backends should usually return False (letting the C-level rasterizer take care of image composition); vector backends should usually return not rcParams["image.composite_image"].

option_scale_image(self) [source]

Return whether arbitrary affine transformations in draw_image() are supported (True for most vector backends).

points_to_pixels(self, points) [source]

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 * dpi/72

Parameters:	pointsfloat or array-like a float or a numpy array of float
Returns:	Points converted to pixels

start_filter(self) [source]

Switch to a temporary renderer for image filtering effects.

Currently only supported by the agg renderer.

start_rasterizing(self) [source]

Switch to the raster renderer.

Used by MixedModeRenderer.

stop_filter(self, filter_func) [source]

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.

Currently only supported by the agg renderer.

stop_rasterizing(self) [source]

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

Used by MixedModeRenderer.

strip_math(self, s) [source]

[Deprecated]

Notes

Deprecated since version 3.1:

class matplotlib.backend_bases.ResizeEvent(name, canvas) [source]

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:	widthint Width of the canvas in pixels. heightint Height of the canvas in pixels.

class matplotlib.backend_bases.ShowBase [source]

Bases: matplotlib.backend_bases._Backend

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

Subclass must override mainloop() method.

class matplotlib.backend_bases.StatusbarBase(toolmanager) [source]

Bases: object

Base class for the statusbar.

set_message(self, s) [source]

Display a message on toolbar or in status bar.

Parameters:	sstr Message text.

class matplotlib.backend_bases.TimerBase(interval=None, callbacks=None) [source]

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.

Subclasses must override the following methods:

• _timer_start: Backend-specific code for starting the timer.
• _timer_stop: Backend-specific code for stopping the timer.

Subclasses may additionally override the following methods:

• _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: The internal function that any timer object should call, which will handle the task of running all callbacks that have been set.

Attributes:

intervalscalar The time between timer events in milliseconds. Default is 1000 ms. single_shotbool Boolean flag indicating whether this timer should operate as single shot (run once and then stop). Defaults to False. callbacksList[Tuple[callable, Tuple, Dict]] Stores list of (func, args, kwargs) 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(self, func, *args, **kwargs) [source]

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

This function returns func, which makes it possible to use it as a decorator.

property interval

remove_callback(self, func, *args, **kwargs) [source]

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. This behavior is deprecated. In the future, *args, **kwargs won't be considered anymore; to keep a specific callback removable by itself, pass it to add_callback as a functools.partial object.

property single_shot

start(self, interval=None) [source]

Start the timer object.

Parameters:	intervalint, optional Timer interval in milliseconds; overrides a previously set interval if provided.

stop(self) [source]

Stop the timer.

class matplotlib.backend_bases.ToolContainerBase(toolmanager) [source]

Bases: object

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

Attributes:	toolmanagerToolManager The tools with which this ToolContainer wants to communicate.

add_tool(self, tool, group, position=- 1) [source]

Adds a tool to this container

Parameters:	tooltool_like The tool to add, see ToolManager.get_tool. groupstr The name of the group to add this tool to. positionint (optional) The position within the group to place this tool. Defaults to end.

add_toolitem(self, name, group, position, image, description, toggle) [source]

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:

namestr Name of the tool to add, this gets used as the tool's ID and as the default label of the buttons groupString Name of the group that this tool belongs to positionInt Position of the tool within its group, if -1 it goes at the End image_fileString Filename of the image for the button or None descriptionString Description of the tool, used for the tooltips toggleBool 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(self, name) [source]

Remove a toolitem from the ToolContainer.

This method must get implemented per backend.

Called when ToolManager emits a tool_removed_event.

Parameters:	namestr Name of the tool to remove.

toggle_toolitem(self, name, toggled) [source]

Toggle the toolitem without firing event

Parameters:	nameString Id of the tool to toggle toggledbool Whether to set this tool as toggled or not.

trigger_tool(self, name) [source]

Trigger the tool

Parameters:	namestr Name (id) of the tool triggered from within the container.

matplotlib.backend_bases.button_press_handler(event, canvas, toolbar=None) [source]

The default Matplotlib button actions for extra mouse buttons.

matplotlib.backend_bases.get_registered_canvas_class(format) [source]

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) [source]

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

Parameters:	eventKeyEvent a key press/release event canvasFigureCanvasBase the backend-specific canvas instance toolbarNavigationToolbar2 the navigation cursor toolbar

matplotlib.backend_bases.register_backend(format, backend, description=None) [source]

Register a backend for saving to a given file format.

Parameters:	formatstr File extension backendmodule string or canvas class Backend for handling file output descriptionstr, default: "" Description of the file type.