matplotlib.backend_bases#

Abstract base classes define the primitives that renderers andgraphics 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 theFigure from the backendspecific 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 classessuch asKeyEvent andMouseEvent store the meta data like keys andbuttons pressed, x and y locations in pixel andAxes coordinates.

ShowBase

The base class for theShow class of each interactive backend; the'show' callable is then set toShow.__call__.

ToolContainerBase

The base class for the Toolbar class of each interactive backend.

classmatplotlib.backend_bases.CloseEvent(name,canvas,guiEvent=None)[source]#

Bases:Event

An event triggered by a figure being closed.

classmatplotlib.backend_bases.DrawEvent(name,canvas,renderer)[source]#

Bases:Event

An event triggered by a draw operation on the canvas.

In most backends, callbacks subscribed to this event will be fired afterthe rendering is complete but before the screen is updated. Any extraartists drawn to the canvas's renderer will be reflected without anexplicit call toblit.

Warning

Callingcanvas.draw andcanvas.blit in these callbacks maynot be safe with all backends and may cause infinite recursion.

A DrawEvent has a number of special attributes in addition to those definedby the parentEvent class.

Attributes:

rendererRendererBase

The renderer for the draw event.

classmatplotlib.backend_bases.Event(name,canvas,guiEvent=None)[source]#

Bases:object

A Matplotlib event.

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

Attributes:

namestr

The event name.

canvasFigureCanvasBase

The backend-specific canvas instance generating the event.

guiEvent

The GUI event that triggered the Matplotlib event.

classmatplotlib.backend_bases.FigureCanvasBase(figure=None)[source]#

Bases:object

The canvas the figure renders into.

Attributes:

figureFigure

A high-level figure instance.

blit(bbox=None)[source]#

Blit the canvas in bbox (default entire canvas).

propertybutton_pick_id#

propertycallbacks#

propertydevice_pixel_ratio#

The ratio of physical to logical pixels used for the canvas on screen.

By default, this is 1, meaning physical and logical pixels are the samesize. Subclasses that support High DPI screens may set this property toindicate that said ratio is different. All Matplotlib interaction,unless working directly with the canvas, remains in logical pixels.

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

Render theFigure.

This method must walk the artist tree, even if no output is produced,because it triggers deferred work that users may want to accessbefore saving output to disk. For example computing limits,auto-limits, and tick values.

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

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

Even if multiple calls todraw_idle occur before control returnsto the GUI event loop, the figure will only be rendered once.

Notes

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

events=['resize_event','draw_event','key_press_event','key_release_event','button_press_event','button_release_event','scroll_event','motion_notify_event','pick_event','figure_enter_event','figure_leave_event','axes_enter_event','axes_leave_event','close_event']#

filetypes={'eps':'EncapsulatedPostscript','jpeg':'JointPhotographicExpertsGroup','jpg':'JointPhotographicExpertsGroup','pdf':'PortableDocumentFormat','pgf':'PGFcodeforLaTeX','png':'PortableNetworkGraphics','ps':'Postscript','raw':'RawRGBAbitmap','rgba':'RawRGBAbitmap','svg':'ScalableVectorGraphics','svgz':'ScalableVectorGraphics','tif':'TaggedImageFileFormat','tiff':'TaggedImageFileFormat','webp':'WebPImageFormat'}#

fixed_dpi=None#

flush_events()[source]#

Flush the GUI events for the figure.

Interactive backends need to reimplement this method.

get_default_filename()[source]#

Return a suitable default filename, including the extension.

classmethodget_default_filetype()[source]#

Return the default savefig file format as specified inrcParams["savefig.format"] (default:'png').

The returned string does not include a period. This method isoverridden in backends that only support a single file type.

classmethodget_supported_filetypes()[source]#

Return dict of savefig file formats supported by this backend.

classmethodget_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 PhotographicExperts Group', and the values are a list of filename extensions usedfor that filetype, such as ['jpg', 'jpeg'].

get_width_height(*,physical=False)[source]#

Return the figure width and height in integral points or pixels.

When the figure is used on High DPI screens (and the backend supportsit), the truncation to integers occurs after scaling by the devicepixel ratio.

Parameters:

physicalbool, default: False

Whether to return true physical pixels or logical pixels. Physicalpixels may be used by backends that support HiDPI, but stillconfigure the canvas using its actual size.

Returns:

width, heightint

The size of the figure, in points or pixels, depending on thebackend.

grab_mouse(ax)[source]#

Set the childAxes which is grabbing the mouse events.

Usually called by the widgets themselves. It is an error to call thisif the mouse is already grabbed by another Axes.

inaxes(xy)[source]#

Return the topmost visibleAxes containing the pointxy.

Parameters:

xy(float, float)

(x, y) pixel positions from left/bottom of the canvas.

Returns:

Axes or None

The topmost visible Axes containing the point, or None if thereis no Axes at the point.

is_saving()[source]#

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

manager_class[source]#

alias ofFigureManagerBase

mpl_connect(s,func)[source]#

Bind functionfunc to events.

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 thesignature:

deffunc(event:Event)->Any

For the location events (button and key press/release), if themouse is over the Axes, theinaxes attribute of the event willbe set to theAxes the event occurs is over, andadditionally, the variablesxdata andydata attributes willbe set to the mouse location in data coordinates. SeeKeyEventandMouseEvent for more info.

Note

If func is a method, this only stores a weak reference to themethod. Thus, the figure does not influence the lifetime ofthe associated object. Usually, you want to make sure that theobject is kept alive throughout the lifetime of the figure byholding a reference to it.

Returns:

cid

A connection id that can be used withFigureCanvasBase.mpl_disconnect.

Examples

defon_press(event):print('you pressed',event.button,event.xdata,event.ydata)cid=canvas.mpl_connect('button_press_event',on_press)

mpl_disconnect(cid)[source]#

Disconnect the callback with idcid.

Examples

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

classmethodnew_manager(figure,num)[source]#

Create a new figure manager forfigure, using this canvas class.

Notes

This method should not be reimplemented in subclasses. Ifcustom manager creation logic is needed, please reimplementFigureManager.create_with_canvas.

new_timer(interval=None,callbacks=None)[source]#

Create a new backend-specific subclass ofTimer.

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

Parameters:

intervalint

Timer interval in milliseconds.

callbackslist[tuple[callable, tuple, dict]]

Sequence of (func, args, kwargs) wherefunc(*args,**kwargs)will be executed by the timer everyinterval.

Callbacks which returnFalse or0 will be removed from thetimer.

Examples

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

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

Render the figure to hardcopy. Set the figure patch face and edgecolors. This is useful because some of the GUIs have a gray figureface color background and you'll probably want to override this onhardcopy.

Parameters:

filenamestr or path-like or file-like

The file where the figure is saved.

dpifloat, default:rcParams["savefig.dpi"] (default:'figure')

The dots per inch to save the figure in.

facecolorcolor or 'auto', default:rcParams["savefig.facecolor"] (default:'auto')

The facecolor of the figure. If 'auto', use the current figurefacecolor.

edgecolorcolor or 'auto', default:rcParams["savefig.edgecolor"] (default:'auto')

The edgecolor of the figure. If 'auto', use the current figureedgecolor.

orientation{'landscape', 'portrait'}, default: 'portrait'

Only currently applies to PostScript printing.

formatstr, optional

Force a specific file format. If not given, the format is inferredfrom thefilename extension, and if that fails fromrcParams["savefig.format"] (default:'png').

bbox_inches'tight' orBbox, default:rcParams["savefig.bbox"] (default:None)

Bounding box in inches: only the given portion of the figure issaved. If 'tight', try to figure out the tight bbox of the figure.

pad_inchesfloat or 'layout', default:rcParams["savefig.pad_inches"] (default:0.1)

Amount of padding in inches around the figure when bbox_inches is'tight'. If 'layout' use the padding from the constrained orcompressed layout engine; ignored if one of those engines is not inuse.

bbox_extra_artistslist ofArtist, optional

A list of extra artists that will be considered when thetight bbox is calculated.

backendstr, optional

Use a non-default backend to render the file, e.g. to render apng file with the "cairo" backend rather than the default "agg",or a pdf file with the "pgf" backend rather than the default"pdf". Note that the default backend is normally sufficient. SeeThe builtin backends for a list of valid backends for eachfile format. Custom backends can be referenced as "module://...".

release_mouse(ax)[source]#

Release the mouse grab held by theAxesax.

Usually called by the widgets. It is ok to call this even ifaxdoesn't have the mouse grab currently.

required_interactive_framework=None#

propertyscroll_pick_id#

set_cursor(cursor)[source]#

Set the current cursor.

This may have no effect if the backend does not display anything.

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

Parameters:

cursorCursors

The cursor to display over the canvas. Note: some backends maychange the cursor for the entire window.

start_event_loop(timeout=0)[source]#

Start a blocking event loop.

Such an event loop is used by interactive functions, such asginput andwaitforbuttonpress, to wait forevents.

The event loop blocks until a callback function triggersstop_event_loop, ortimeout is reached.

Iftimeout is 0 or negative, never timeout.

Only interactive backends need to reimplement this method and it reliesonflush_events being properly implemented.

Interactive backends should implement this in a more native way.

stop_event_loop()[source]#

Stop the current blocking event loop.

Interactive backends need to reimplement this to matchstart_event_loop

supports_blit=False#

classmatplotlib.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 abackend-independent way. It's an adapter for the real (GUI) framework thatrepresents the visual figure on screen.

The figure manager is connected to a specific canvas instance, which in turnis connected to a specific figure instance. To access a figure manager fora given figure in user code, you typically usefig.canvas.manager.

GUI backends derive from this class to translate common operations suchasshow orresize to the GUI-specific code. Non-GUI backends do notsupport these operations and 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 byhooking up thekey_press_handler to the matplotlib event system. Thisensures the same shortcuts and mouse actions across backends.

Other operations

Subclasses will have additional attributes and functions to accessadditional functionality. This is of course backend-specific. For example,most GUI backends havewindow andtoolbar attributes that giveaccess 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)

classmethodcreate_with_canvas(canvas_class,figure,num)[source]#

Create a manager for a givenfigure using a specificcanvas_class.

Backends should override this method if they have specific needs forsetting up the canvas or the manager.

destroy()[source]#

full_screen_toggle()[source]#

get_window_title()[source]#

Return the title text of the window containing the figure.

classmethodpyplot_show(*,block=None)[source]#

Show all figures. This method is the implementation ofpyplot.show.

To customize the behavior ofpyplot.show, interactive backendsshould usually overridestart_main_loop; if morecustomized logic is necessary,pyplot_show canalso be overridden.

Parameters:

blockbool, optional

Whether to block by callingstart_main_loop. The default,None, means to block if we are neither in IPython's%pylab modenor ininteractive mode.

resize(w,h)[source]#

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

set_window_title(title)[source]#

Set the title text of the window containing the figure.

Examples

>>>fig=plt.figure()>>>fig.canvas.manager.set_window_title('My figure')

show()[source]#

For GUI backends, show the figure window and redraw.For non-GUI backends, raise an exception, unless running headless (i.e.on Linux with an unset DISPLAY); this exception is converted to awarning inFigure.show.

classmethodstart_main_loop()[source]#

Start the main event loop.

This method is called byFigureManagerBase.pyplot_show, which is theimplementation ofpyplot.show. To customize the behavior ofpyplot.show, interactive backends should usually overridestart_main_loop; if more customized logic isnecessary,pyplot_show can also be overridden.

classmatplotlib.backend_bases.GraphicsContextBase[source]#

Bases:object

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

copy_properties(gc)[source]#

Copy properties fromgc to self.

get_alpha()[source]#

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

get_antialiased()[source]#

Return whether the object should try to do antialiased rendering.

get_capstyle()[source]#

Return theCapStyle.

get_clip_path()[source]#

Return the clip path in the form (path, transform), where pathis aPath instance, and transform isan affine transform to apply to the path before clipping.

get_clip_rectangle()[source]#

Return the clip rectangle as aBbox instance.

get_dashes()[source]#

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

Seeset_dashes for details.

Default value is (None, None).

get_forced_alpha()[source]#

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

get_gid()[source]#

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

get_hatch()[source]#

Get the current hatch style.

get_hatch_color()[source]#

Get the hatch color.

get_hatch_linewidth()[source]#

Get the hatch linewidth.

get_hatch_path(density=6.0)[source]#

Return aPath for the current hatch.

get_joinstyle()[source]#

Return theJoinStyle.

get_linewidth()[source]#

Return the line width in points.

get_rgb()[source]#

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

get_sketch_params()[source]#

Return the sketch parameters for the artist.

Returns:

tuple orNone

A 3-tuple with the following elements:

• scale: The amplitude of the wiggle perpendicular to thesource line.

• length: The length of the wiggle along the line.

• randomness: The scale factor by which the length isshrunken or expanded.

May returnNone if no sketch parameters were set.

get_snap()[source]#

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

Return a url if one is set, None otherwise.

restore()[source]#

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

set_alpha(alpha)[source]#

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

Ifalpha=None (the default), the alpha components of theforeground and fill colors will be used to set their respectivetransparencies (where applicable); otherwise,alpha will overridethem.

set_antialiased(b)[source]#

Set whether object should be drawn with antialiased rendering.

set_capstyle(cs)[source]#

Set how to draw endpoints of lines.

Parameters:

csCapStyle or {'butt', 'projecting', 'round'}

set_clip_path(path)[source]#

Set the clip path to aTransformedPath or None.

set_clip_rectangle(rectangle)[source]#

Set the clip rectangle to aBbox or None.

set_dashes(dash_offset,dash_list)[source]#

Set the dash style for the gc.

Parameters:

dash_offsetfloat

Distance, in points, into the dash pattern at which tostart the pattern. It is usually set to 0.

dash_listarray-like or None

The on-off sequence as points. None specifies a solid line. Allvalues must otherwise be non-negative (\(\ge 0\)).

Notes

See p. 666 of the PostScriptLanguage Referencefor more info.

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

Set the foreground color.

Parameters:

fgcolor

isRGBAbool

Iffg is known to be an(r,g,b,a) tuple,isRGBA can beset to True to improve performance.

set_gid(id)[source]#

Set the id.

set_hatch(hatch)[source]#

Set the hatch style (for fills).

set_hatch_color(hatch_color)[source]#

Set the hatch color.

set_hatch_linewidth(hatch_linewidth)[source]#

Set the hatch linewidth.

set_joinstyle(js)[source]#

Set how to draw connections between line segments.

Parameters:

jsJoinStyle or {'miter', 'round', 'bevel'}

set_linewidth(w)[source]#

Set the linewidth in points.

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

Set the sketch parameters.

Parameters:

scalefloat, optional

The amplitude of the wiggle perpendicular to the source line, inpixels. If scale isNone, or not provided, no sketch filter willbe 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(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(url)[source]#

Set the url for links in compatible backends.

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

Bases:LocationEvent

A key event (key press, key release).

A KeyEvent has a number of special attributes in addition to those definedby the parentEvent andLocationEvent classes.

Attributes:

keyNone or str

The key(s) pressed. Could beNone, a single case sensitive Unicodecharacter ("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").

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 keyis itself a modifier key, therefore "ctrl+alt" and "alt+control" can bothbe valid key values.

Examples

defon_key(event):print('you pressed',event.key,event.xdata,event.ydata)cid=fig.canvas.mpl_connect('key_press_event',on_key)

classmatplotlib.backend_bases.LocationEvent(name,canvas,x,y,guiEvent=None,*,modifiers=None)[source]#

Bases:Event

An event that has a screen location.

A LocationEvent has a number of special attributes in addition to thosedefined by the parentEvent class.

Attributes:

x, yint or None

Event location in pixels from bottom left of canvas.

inaxesAxes or None

TheAxes instance over which the mouse is, if any.

xdata, ydatafloat or None

Data coordinates of the mouse withininaxes, orNone if the mouseis not over an Axes.

modifiersfrozenset

The keyboard modifiers currently being pressed (except for KeyEvent).

classmatplotlib.backend_bases.MouseButton(*values)[source]#

Bases:IntEnum

BACK=8[source]#

FORWARD=9[source]#

LEFT=1[source]#

MIDDLE=2[source]#

RIGHT=3[source]#

classmatplotlib.backend_bases.MouseEvent(name,canvas,x,y,button=None,key=None,step=0,dblclick=False,guiEvent=None,*,buttons=None,modifiers=None)[source]#

Bases:LocationEvent

A mouse event ('button_press_event', 'button_release_event', 'scroll_event', 'motion_notify_event').

A MouseEvent has a number of special attributes in addition to thosedefined by the parentEvent andLocationEvent classes.

Attributes:

buttonNone orMouseButton or {'up', 'down'}

The button pressed. 'up' and 'down' are used for scroll events.

Note that LEFT and RIGHT actually refer to the "primary" and"secondary" buttons, i.e. if the user inverts their left and rightbuttons ("left-handed setting") then the LEFT button will be the onephysically on the right.

If this is unset,name is "scroll_event", andstep is nonzero, thenthis will be set to "up" or "down" depending on the sign ofstep.

buttonsNone or frozenset

For 'motion_notify_event', the mouse buttons currently being pressed(a set of zero or more MouseButtons);for other events, None.

Note

For 'motion_notify_event', this attribute is more accurate thanthebutton (singular) attribute, which is obtained from the last'button_press_event' or 'button_release_event' that occurred withinthe canvas (and thus 1. be wrong if the last change in mouse stateoccurred when the canvas did not have focus, and 2. cannot reportwhen multiple buttons are pressed).

This attribute is not set for 'button_press_event' and'button_release_event' because GUI toolkits are inconsistent as towhether they report the button statebefore orafter thepress/release occurred.

Warning

On macOS, the Tk backends only report a single button even ifmultiple buttons are pressed.

keyNone or str

The key pressed when the mouse event triggered, e.g. 'shift'.SeeKeyEvent.

Warning

This key is currently obtained from the last 'key_press_event' or'key_release_event' that occurred within the canvas. Thus, if thelast change of keyboard state occurred while the canvas did not havefocus, this attribute will be wrong. On the other hand, themodifiers attribute should always be correct, but it can onlyreport on modifier keys.

stepfloat

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'snot used in 'button_release_event'.

Examples

defon_press(event):print('you pressed',event.button,event.xdata,event.ydata)cid=fig.canvas.mpl_connect('button_press_event',on_press)

classmatplotlib.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'. SeeFigureCanvasBase.mpl_connect() for more information.

They must also define

save_figure()

Save the current figure.

draw_rubberband() (optional)

Draw the zoom to rect "rubberband" rectangle.

set_message() (optional)

Display message.

set_history_buttons() (optional)

You can change the history back / forward buttons to indicate disabled / enabledstate.

and override__init__ to set up the toolbar -- without forgetting tocall the base-class init. Typically,__init__ needs to set up toolbarbuttons connected to thehome,back,forward,pan,zoom, andsave_figure methods and using standard icons in the "images" subdirectoryof the data path.

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

UNKNOWN_SAVED_STATUS=<objectobject>#

back(*args)[source]#

Move back up the view lim stack.

For convenience of being directly connected as a GUI callback, whichoften get passed additional parameters, this method accepts arbitraryparameters, but does not use them.

configure_subplots(*args)[source]#

drag_pan(event)[source]#

Callback for dragging in pan/zoom mode.

drag_zoom(event)[source]#

Callback for dragging in zoom mode.

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

Draw a rectangle rubberband to indicate zoom limits.

Note that it is not guaranteed thatx0<=x1 andy0<=y1.

forward(*args)[source]#

Move forward in the view lim stack.

For convenience of being directly connected as a GUI callback, whichoften get passed additional parameters, this method accepts arbitraryparameters, but does not use them.

home(*args)[source]#

Restore the original view.

For convenience of being directly connected as a GUI callback, whichoften get passed additional parameters, this method accepts arbitraryparameters, but does not use them.

mouse_move(event)[source]#

pan(*args)[source]#

Toggle the pan/zoom tool.

Pan with left button, zoom with right.

press_pan(event)[source]#

Callback for mouse button press in pan/zoom mode.

press_zoom(event)[source]#

Callback for mouse button press in zoom to rect mode.

push_current()[source]#

Push the current view limits and position onto the stack.

release_pan(event)[source]#

Callback for mouse button release in pan/zoom mode.

release_zoom(event)[source]#

Callback for mouse button release in zoom to rect mode.

remove_rubberband()[source]#

Remove the rubberband.

save_figure(*args)[source]#

Save the current figure.

Backend implementations may choose to returnthe absolute path of the saved file, if any, asa string.

If no file is created thenNone is returned.

If the backend does not implement this functionalitythenNavigationToolbar2.UNKNOWN_SAVED_STATUS is returned.

Returns:

str orNavigationToolbar2.UNKNOWN_SAVED_STATUS orNone

The filepath of the saved figure.ReturnsNone if figure is not saved.ReturnsNavigationToolbar2.UNKNOWN_SAVED_STATUS whenthe backend does not provide the information.

set_history_buttons()[source]#

Enable or disable the back/forward button.

set_message(s)[source]#

Display a message on toolbar or in status bar.

toolitems=(('Home','Resetoriginalview','home','home'),('Back','Backtopreviousview','back','back'),('Forward','Forwardtonextview','forward','forward'),(None,None,None,None),('Pan','Leftbuttonpans,Rightbuttonzooms\nx/yfixesaxis,CTRLfixesaspect','move','pan'),('Zoom','Zoomtorectangle\nx/yfixesaxis','zoom_to_rect','zoom'),('Subplots','Configuresubplots','subplots','configure_subplots'),(None,None,None,None),('Save','Savethefigure','filesave','save_figure'))#

update()[source]#

Reset the Axes stack.

zoom(*args)[source]#

exceptionmatplotlib.backend_bases.NonGuiException[source]#

Bases:Exception

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

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

Bases:Event

A pick event.

This event is fired when the user picks a location on the canvassufficiently close to an artist that has been made pickable withArtist.set_picker.

A PickEvent has a number of special attributes in addition to those definedby the parentEvent class.

Attributes:

mouseeventMouseEvent

The mouse event that generated the pick.

artistArtist

The picked artist. Note that artists are not pickable by default(seeArtist.set_picker).

other

Additional attributes may be present depending on the type of thepicked object; e.g., aLine2D pick may define different extraattributes than aPatchCollection pick.

Examples

Bind a functionon_pick() to pick events, that prints the coordinatesof the picked data point:

ax.plot(np.rand(100),'o',picker=5)# 5 points tolerancedefon_pick(event):line=event.artistxdata,ydata=line.get_data()ind=event.indprint(f'on pick line:{xdata[ind]:.3f},{ydata[ind]:.3f}')cid=fig.canvas.mpl_connect('pick_event',on_pick)

classmatplotlib.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 fullfunctionality (though just implementingdraw_path alone would give ahighly capable backend):

• draw_path

• draw_image

• draw_gouraud_triangles

The following methodsshould be implemented in the backend foroptimization reasons:

• draw_text

• draw_markers

• draw_path_collection

• draw_quad_mesh

close_group(s)[source]#

Close a grouping element with labels.

Only used by the SVG renderer.

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

Draw a series of Gouraud triangles.

Parameters:

gcGraphicsContextBase

The graphics context.

triangles_array(N, 3, 2) array-like

Array ofN (x, y) points for the triangles.

colors_array(N, 3, 4) array-like

Array ofN RGBA colors for each point of the triangles.

transformTransform

An affine transform to apply to the points.

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

Draw an RGBA image.

Parameters:

gcGraphicsContextBase

A graphics context with clipping information.

xfloat

The distance in physical units (i.e., dots or pixels) from the lefthand side of the canvas.

yfloat

The distance in physical units (i.e., dots or pixels) from thebottom side of the canvas.

im(N, M, 4) array ofnumpy.uint8

An array of RGBA pixels.

transformAffine2DBase

If and only if the concrete backend is written such thatoption_scale_image returnsTrue, an affine transformation(i.e., anAffine2DBase)may be passed todraw_image. Thetranslation vector of the transformation is given in physical units(i.e., dots or pixels). Note that the transformation does notoverridex andy, and has to be appliedbefore translatingthe result byx andy (this can be accomplished by addingxandy to the translation vector defined bytransform).

draw_markers(gc,marker_path,marker_trans,path,trans,rgbFace=None)[source]#

Draw a marker at each ofpath's vertices (excluding control points).

The base (fallback) implementation makes multiple calls todraw_path.Backends may want to override this method in order to draw the markeronly once and reuse it multiple times.

Parameters:

gcGraphicsContextBase

The graphics context.

marker_pathPath

The path for the marker.

marker_transTransform

An affine transform applied to the marker.

pathPath

The locations to draw the markers.

transTransform

An affine transform applied to the path.

rgbFacecolor, optional

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

Draw aPath instance using the given affine transform.

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

Draw a collection ofpaths.

Each path is first transformed by the corresponding entryinall_transforms (a list of (3, 3) matrices) and then bymaster_transform. They are then translated by the correspondingentry inoffsets, which has been first transformed byoffset_trans.

facecolors,edgecolors,linewidths,linestyles, andantialiased are lists that set the corresponding properties.

offset_position is unused now, but the argument is kept forbackwards compatibility.

The base (fallback) implementation makes multiple calls todraw_path.Backends may want to override this in order to render each set ofpath data only once, and then reference that path multiple times withthe different offsets, colors, styles etc. The generator methods_iter_collection_raw_paths and_iter_collection are provided tohelp with (and standardize) the implementation across backends. Itis highly recommended to use those generators, so that changes to thebehavior ofdraw_path_collection can be made globally.

draw_quad_mesh(gc,master_transform,meshWidth,meshHeight,coordinates,offsets,offsetTrans,facecolors,antialiased,edgecolors)[source]#

Draw a quadmesh.

The base (fallback) implementation converts the quadmesh to paths andthen callsdraw_path_collection.

draw_tex(gc,x,y,s,prop,angle,*,mtext=None)[source]#

Draw a TeX 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 TeX text string.

propFontProperties

The font properties.

anglefloat

The rotation angle in degrees anti-clockwise.

mtextText

The original text object to be rendered.

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

Draw a 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.

propFontProperties

The font properties.

anglefloat

The rotation angle in degrees anti-clockwise.

ismathbool or "TeX"

If True, use mathtext parser.

mtextText

The original text object to be rendered.

Notes

Notes for backend implementers:

RendererBase.draw_text also supports passing "TeX" to theismathparameter to use TeX rendering, but this is not required for actualrendering backends, and indeed many builtin backends do not supportthis. Rather, TeX rendering is provided bydraw_tex.

flipy()[source]#

Return whether y values increase from top to bottom.

Note that this only affects drawing of texts.

get_canvas_width_height()[source]#

Return the canvas width and height in display coords.

get_image_magnification()[source]#

Get the factor by which to magnify images passed todraw_image.Allows a backend to have images at a different resolution to otherartists.

get_texmanager()[source]#

Return theTexManager instance.

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

Get the width, height, and descent (offset from the bottom to the baseline), indisplay coords, of the strings withFontPropertiesprop.

Whitespace at the start and the end ofs is included in the reported width.

new_gc()[source]#

Return an instance of aGraphicsContextBase.

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

Open a grouping element with labels andgid (if set) as id.

Only used by the SVG renderer.

option_image_nocomposite()[source]#

Return whether image composition by Matplotlib should be skipped.

Raster backends should usually return False (letting the C-levelrasterizer take care of image composition); vector backends shouldusually returnnotrcParams["image.composite_image"].

option_scale_image()[source]#

Return whether arbitrary affine transformations indraw_image aresupported (True for most vector backends).

points_to_pixels(points)[source]#

Convert points to display units.

You need to override this function (unless your backenddoesn't have a dpi, e.g., postscript or svg). Some imagingsystems assume some value for pixels per inch:

pointstopixels=points*pixels_per_inch/72*dpi/72

Parameters:

pointsfloat or array-like

Returns:

Points converted to pixels

start_filter()[source]#

Switch to a temporary renderer for image filtering effects.

Currently only supported by the agg renderer.

start_rasterizing()[source]#

Switch to the raster renderer.

Used byMixedModeRenderer.

stop_filter(filter_func)[source]#

Switch back to the original renderer. The contents of the temporaryrenderer is processed with thefilter_func and is drawn on theoriginal renderer as an image.

Currently only supported by the agg renderer.

stop_rasterizing()[source]#

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

Used byMixedModeRenderer.

classmatplotlib.backend_bases.ResizeEvent(name,canvas)[source]#

Bases:Event

An event triggered by a canvas resize.

A ResizeEvent has a number of special attributes in addition to thosedefined by the parentEvent class.

Attributes:

widthint

Width of the canvas in pixels.

heightint

Height of the canvas in pixels.

classmatplotlib.backend_bases.ShowBase[source]#

Bases:_Backend

Simple base class to generate ashow() function in backends.

Subclass must overridemainloop() method.

classmatplotlib.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 theirown timing mechanisms so that the timer events are integrated into theirevent 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 shotoperating mode, if supported by the timer object. If not, theTimerclass itself will store the flag and the_on_timer method should beoverridden to support such behavior.

• _timer_set_interval: Code for setting the interval on the timer, ifthere 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.

Parameters:

intervalint, default: 1000ms

The time between timer events in milliseconds. Will be stored astimer.interval.

callbackslist[tuple[callable, tuple, dict]]

List of (func, args, kwargs) tuples that will be called upon timerevents. This list is accessible astimer.callbacks and can bemanipulated directly, or the functionsadd_callbackandremove_callback can be used.

add_callback(func,*args,**kwargs)[source]#

Registerfunc to be called by timer when the event fires. Anyadditional arguments provided will be passed tofunc.

This function returnsfunc, which makes it possible to use it as adecorator.

propertyinterval#

The time between timer events, in milliseconds.

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

Removefunc from list of callbacks.

args andkwargs are optional and used to distinguish between copiesof the same function registered to be called with different arguments.This behavior is deprecated. In the future,*args,**kwargs won'tbe considered anymore; to keep a specific callback removable by itself,pass it toadd_callback as afunctools.partial object.

propertysingle_shot#

Whether this timer should stop after a single run.

start(interval=<deprecatedparameter>)[source]#

Start the timer object.

Parameters:

intervalint, optional

Timer interval in milliseconds; overrides a previously set intervalif provided.

stop()[source]#

Stop the timer.

classmatplotlib.backend_bases.ToolContainerBase(toolmanager)[source]#

Bases:object

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

Attributes:

toolmanagerToolManager

The tools with which thisToolContainer wants to communicate.

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

Add a tool to this container.

Parameters:

tooltool_like

The tool to add, seeToolManager.get_tool.

groupstr

The name of the group to add this tool to.

positionint, default: -1

The position within the group to place this tool.

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

A hook to add a toolitem to the container.

This hook must be implemented in each backend and contains thebackend-specific code to add an element to the toolbar.

Warning

This is part of the backend implementation and shouldnot be called by end-users. They should instead callToolContainerBase.add_tool.

The callback associated with the button click eventmust beexactlyself.trigger_tool(name).

Parameters:

namestr

Name of the tool to add, this gets used as the tool's ID and as thedefault label of the buttons.

groupstr

Name of the group that this tool belongs to.

positionint

Position of the tool within its group, if -1 it goes at the end.

imagestr

Filename of the image for the button orNone.

descriptionstr

Description of the tool, used for the tooltips.

togglebool

• True : The button is a toggle (change the pressed/unpressedstate between consecutive clicks).

• False : The button is a normal button (returns to unpressedstate after release).

remove_toolitem(name)[source]#

A hook to remove a toolitem from the container.

This hook must be implemented in each backend and contains thebackend-specific code to remove an element from the toolbar; it iscalled whenToolManager emits atool_removed_event.

Because some tools are present only on theToolManager but not ontheToolContainer, this method must be a no-op when called on a toolabsent from the container.

Warning

This is part of the backend implementation and shouldnot be called by end-users. They should instead callToolManager.remove_tool.

Parameters:

namestr

Name of the tool to remove.

set_message(s)[source]#

Display a message on the toolbar.

Parameters:

sstr

Message text.

toggle_toolitem(name,toggled)[source]#

A hook to toggle a toolitem without firing an event.

This hook must be implemented in each backend and contains thebackend-specific code to silently toggle a toolbar element.

Warning

This is part of the backend implementation and shouldnot be called by end-users. They should instead callToolManager.trigger_tool orToolContainerBase.trigger_tool(which are equivalent).

Parameters:

namestr

Id of the tool to toggle.

toggledbool

Whether to set this tool as toggled or not.

trigger_tool(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=None,toolbar=None)[source]#

The default Matplotlib button actions for extra mouse buttons.

Parameters are as forkey_press_handler, except thatevent is aMouseEvent.

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=None,toolbar=None)[source]#

Implement the default Matplotlib key bindings for the canvas and toolbardescribed atNavigation keyboard shortcuts.

Parameters:

eventKeyEvent

A key press/release event.

canvasFigureCanvasBase, default:event.canvas

The backend-specific canvas instance. This parameter is kept forback-compatibility, but, if set, should always be equal toevent.canvas.

toolbarNavigationToolbar2, default:event.canvas.toolbar

The navigation cursor toolbar. This parameter is kept forback-compatibility, but, if set, should always be equal toevent.canvas.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.