The mplcursors API


mplcursors.Cursor(artists, *[, multiple, ...]) A cursor for selecting Matplotlib artists.
mplcursors.cursor([pickables]) Create a Cursor for a list of artists, containers, and axes.
mplcursors.Selection(artist, target, dist, ...)
mplcursors.compute_pick(artist, event) Find whether artist has been picked by event.
mplcursors.get_ann_text(sel) Compute an annotating text for a Selection (passed unpacked).
mplcursors.make_highlight(sel, *, ...) Create a highlight for a Selection.

class mplcursors.Cursor(artists, *, multiple=False, highlight=False, hover=False, bindings=None, annotation_kwargs=None, annotation_positions=None, highlight_kwargs=None)[source]

Bases: object

A cursor for selecting Matplotlib artists.

bindings

dict – See the bindings keyword argument to the constructor.

annotation_kwargs

dict – See the annotation_kwargs keyword argument to the constructor.

annotation_positions

dict – See the annotation_positions keyword argument to the constructor.

highlight_kwargs

dict – See the highlight_kwargs keyword argument to the constructor.

__init__(artists, *, multiple=False, highlight=False, hover=False, bindings=None, annotation_kwargs=None, annotation_positions=None, highlight_kwargs=None)[source]

Construct a cursor.

Parameters:
  • artists (List[Artist]) – A list of artists that can be selected by this cursor.
  • multiple (bool, optional) – Whether multiple artists can be “on” at the same time (defaults to False).
  • highlight (bool, optional) – Whether to also highlight the selected artist. If so, “highlighter” artists will be placed as the first item in the extras attribute of the Selection.
  • hover (bool, optional) – Whether to select artists upon hovering instead of by clicking. (Hovering over an artist while a button is pressed will not trigger a selection; right clicking on an annotation will still remove it.)
  • bindings (dict, optional) –

    A mapping of button and keybindings to actions. Valid entries are:

    ‘select’ mouse button to select an artist (default: 1)
    ‘deselect’ mouse button to deselect an artist (default: 3)
    ‘left’ move to the previous point in the selected path, or to the left in the selected image (default: shift+left)
    ‘right’ move to the next point in the selected path, or to the right in the selected image (default: shift+right)
    ‘up’ move up in the selected image (default: shift+up)
    ‘down’ move down in the selected image (default: shift+down)
    ‘toggle_enabled’ toggle whether the cursor is active (default: e)
    ‘toggle_visible’ toggle default cursor visibility and apply it to all cursors (default: v)

    Missing entries will be set to the defaults. In order to not assign any binding to an action, set it to None.

  • annotation_kwargs (dict, optional) – Keyword argments passed to the annotate call.
  • annotation_positions (List[dict], optional) – List of positions tried by the annotation positioning algorithm.
  • highlight_kwargs (dict, optional) – Keyword arguments used to create a highlighted artist.
add_highlight(artist, *args, **kwargs)[source]

Create, add, and return a highlighting artist.

This method is should be called with an “unpacked” Selection, possibly with some fields set to None.

It is up to the caller to register the artist with the proper Selection (by calling sel.extras.append on the result of this method) in order to ensure cleanup upon deselection.

add_selection(pi)[source]

Create an annotation for a Selection and register it.

Returns a new Selection, that has been registered by the Cursor, with the added annotation set in the annotation field and, if applicable, the highlighting artist in the extras field.

Emits the "add" event with the new Selection as argument. When the event is emitted, the position of the annotation is temporarily set to (nan, nan); if this position is not explicitly set by a callback, then a suitable position will be automatically computed.

Likewise, if the text alignment is not explicitly set but the position is, then a suitable alignment will be automatically computed.

artists

The tuple of selectable artists.

connect(event, func=None)[source]

Connect a callback to a Cursor event; return the callback.

Two events can be connected to:

  • callbacks connected to the "add" event are called when a Selection is added, with that selection as only argument;
  • callbacks connected to the "remove" event are called when a Selection is removed, with that selection as only argument.

This method can also be used as a decorator:

@cursor.connect("add")
def on_add(sel):
    ...

Examples of callbacks:

# Change the annotation text and alignment:
lambda sel: sel.annotation.set(
    text=sel.artist.get_label(),  # or use e.g. sel.target.index
    ha="center", va="bottom")

# Make label non-draggable:
lambda sel: sel.draggable(False)
disconnect(event, cb)[source]

Disconnect a previously connected callback.

If a callback is connected multiple times, only one connection is removed.

enabled

Whether clicks are registered for picking and unpicking events.

remove()[source]

Remove a cursor.

Remove all Selections, disconnect all callbacks, and allow the cursor to be garbage collected.

remove_selection(sel)[source]

Remove a Selection.

selections

The tuple of current Selections.

visible

Whether selections are visible by default.

Setting this property also updates the visibility status of current selections.

mplcursors.cursor(pickables=None, **kwargs)[source]

Create a Cursor for a list of artists, containers, and axes.

Parameters:
  • pickables (Optional[List[Union[Artist, Container, Axes, Figure]]]) – All artists and containers in the list or on any of the axes or figures passed in the list are selectable by the constructed Cursor. Defaults to all artists and containers on any of the figures that pyplot is tracking. Note that the latter will only work when relying on pyplot, not when figures are directly instantiated (e.g., when manually embedding Matplotlib in a GUI toolkit).
  • **kwargs – Keyword arguments are passed to the Cursor constructor.
class mplcursors.Selection(artist, target, dist, annotation, extras)

Bases: tuple

annotation

The instantiated matplotlib.text.Annotation.

artist

The selected artist.

dist

The distance from the click to the target, in pixels.

extras

An additional list of artists (e.g., highlighters) that will be cleared at the same time as the annotation.

target

The point picked within the artist, in data coordinates.

mplcursors.compute_pick(artist, event)[source]

Find whether artist has been picked by event.

If it has, return the appropriate Selection; otherwise return None.

This is a single-dispatch function; implementations for various artist classes follow.

mplcursors.get_ann_text(sel)[source]

Compute an annotating text for a Selection (passed unpacked).

This is a single-dispatch function; implementations for various artist classes follow.

mplcursors.make_highlight(sel, *, highlight_kwargs)[source]

Create a highlight for a Selection.

This is a single-dispatch function; implementations for various artist classes follow.