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.HoverMode`(value[, names, module, ...])
`mplcursors.Selection`(artist, target_, index, ...)	A selection.
`mplcursors.compute_pick`()	Find whether artist has been picked by event.
`mplcursors.get_ann_text`()	Compute an annotating text for an (unpacked) `Selection`.
`mplcursors.move`()	Move an (unpacked) `Selection` following a keypress.
`mplcursors.make_highlight`()	Create a highlight for an (unpacked) `Selection`.

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

A cursor for selecting Matplotlib artists.

bindings#

See the bindings keyword argument to the constructor.

Type:: dict

annotation_kwargs#

See the annotation_kwargs keyword argument to the constructor.

Type:: dict

annotation_positions#

See the annotation_positions keyword argument to the constructor.

Type:: dict

highlight_kwargs#

See the highlight_kwargs keyword argument to the constructor.

Type:: dict

__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, default: False) – Whether multiple artists can be “on” at the same time. If on, cursor dragging is disabled (so that one does not end up with many cursors on top of one another).
highlight (bool, default: False) – 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 (HoverMode, default: False) –
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.) Possible values are
- False, alias HoverMode.NoHover: hovering is inactive.
- True, alias HoverMode.Persistent: hovering is active; annotations remain in place even after the mouse moves away from the artist (until another artist is selected, if multiple is False).
- 2, alias HoverMode.Transient: hovering is active; annotations are removed as soon as the mouse moves away from the artist.

bindings (dict, optional) –

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

’select’	mouse button to select an artist (default: `MouseButton.LEFT`)
’deselect’	mouse button to deselect an artist (default: `MouseButton.RIGHT`)
’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. Modifier keys (or other event properties) can be set for mouse button bindings by passing them as e.g. {"button": 1, "key": "control"}.

annotation_kwargs (dict, default: {}) – Keyword argments passed to the annotate call.
annotation_positions (List[dict], optional) – List of positions tried by the annotation positioning algorithm. The default is to try four positions, 15 points to the NW, NE, SE, and SW from the selected point; annotations that stay within the axes are preferred.
highlight_kwargs (dict, default: {}) – Keyword arguments used to create a highlighted artist.

property artists#: The tuple of selectable artists.

property enabled#: Whether clicks are registered for picking and unpicking events.

property selections#: The tuple of current Selections.

property visible#

Whether selections are visible by default.

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

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.

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.

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.index
    ha="center", va="bottom")

# Make label non-draggable:
lambda sel: sel.draggable(False)

Note that when a single event causes both the removal of an “old” selection and the addition of a “new” one (typically, clicking on an artist when another one is selected, or hovering – both assuming that multiple=False), the “add” callback is called first. This allows it, in particular, to “cancel” the addition (by immediately removing the “new” selection) and thus avoid removing the “old” selection. However, this call order may change in a future release.

disconnect(event, cb)[source]#

Disconnect a previously connected callback.

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

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.

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.HoverMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

NoHover = 0#

Persistent = 1#

Transient = 2#

class mplcursors.Selection(artist, target_, index, dist, annotation, extras)#

A selection.

Although this class is implemented as a namedtuple (to simplify the dispatching of compute_pick, get_ann_text, and make_highlight), only the field names should be considered stable API. The number and order of fields are subject to change with no notice.

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.

index#: The index of the selected point, within the artist data.

property target#: The point picked within the artist, in data coordinates.

mplcursors.compute_pick(artist, event)[source]#

mplcursors.compute_pick(artist: Line2D, event)

mplcursors.compute_pick(artist: Rectangle, event)

mplcursors.compute_pick(artist: Polygon, event)

mplcursors.compute_pick(artist: PathPatch, event)

mplcursors.compute_pick(artist: PathCollection, event)

mplcursors.compute_pick(artist: PatchCollection, event)

mplcursors.compute_pick(artist: LineCollection, event)

mplcursors.compute_pick(artist: AxesImage, event)

mplcursors.compute_pick(artist: Quiver, event)

mplcursors.compute_pick(artist: Barbs, event)

mplcursors.compute_pick(artist: Text, event)

mplcursors.compute_pick(artist: ContainerArtist, event)

mplcursors.compute_pick(container: BarContainer, event)

mplcursors.compute_pick(container: ErrorbarContainer, event)

mplcursors.compute_pick(container: StemContainer, event)

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(artist, target_, index, dist, annotation, extras)[source]#

mplcursors.get_ann_text(artist: Patch, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: PathCollection, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: PatchCollection, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: LineCollection, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: Line2D, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: AxesImage, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: Barbs, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: Quiver, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(artist: ContainerArtist, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(container: BarContainer, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(container: ErrorbarContainer, target_, index, dist, annotation, extras)

mplcursors.get_ann_text(container: StemContainer, target_, index, dist, annotation, extras)

Compute an annotating text for an (unpacked) Selection.

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

mplcursors.move(artist, target_, index, dist, annotation, extras, *, key)[source]#

mplcursors.move(artist: Line2D, target_, index, dist, annotation, extras, *, key)

mplcursors.move(artist: PathCollection, target_, index, dist, annotation, extras, *, key)

mplcursors.move(artist: AxesImage, target_, index, dist, annotation, extras, *, key)

mplcursors.move(artist: ContainerArtist, target_, index, dist, annotation, extras, *, key)

mplcursors.move(container: ErrorbarContainer, target_, index, dist, annotation, extras, *, key)

Move an (unpacked) Selection following a keypress.

This function is used to implement annotation displacement through the keyboard.

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

mplcursors.make_highlight(artist, target_, index, dist, annotation, extras, *, highlight_kwargs)[source]#

mplcursors.make_highlight(artist: Line2D, target_, index, dist, annotation, extras, *, highlight_kwargs)

mplcursors.make_highlight(artist: PathCollection, target_, index, dist, annotation, extras, *, highlight_kwargs)

Create a highlight for an (unpacked) Selection.

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