mplcursors package

Module contents

class mplcursors.Cursor(artists, *, multiple=False, highlight=False, hover=False, bindings=mappingproxy({'toggle_visibility': 'd', 'deselect': 3, 'right': 'shift+right', 'select': 1, 'toggle_enabled': 't', 'up': 'shift+up', 'down': 'shift+down', 'left': 'shift+left'}))[source]

Bases: object

A cursor for selecting artists on a matplotlib figure.

__init__(artists, *, multiple=False, highlight=False, hover=False, bindings=mappingproxy({'toggle_visibility': 'd', 'deselect': 3, 'right': 'shift+right', 'select': 1, 'toggle_enabled': 't', 'up': 'shift+up', 'down': 'shift+down', 'left': 'shift+left'}))[source]

Construct a cursor.

Parameters:
  • artists (List[Artist]) – A list of artists that can be selected by this cursor.
  • multiple (bool) – Whether multiple artists can be “on” at the same time (defaults to False).
  • highlight (bool) – 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.
  • bindings (dict) –

    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_visibility’ toggle visibility of all cursors (default: d)
    ‘toggle_enabled’ toggle whether the cursor is active (default: t)
  • hover (bool) – Whether to select artists upon hovering instead of by clicking.
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 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.

artists

The tuple of selectable artists.

connect(event, func=None)[source]

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

Two classes of event can be emitted, both with a Selection as single argument:

The callback registry relies on matplotlib‘s implementation; in particular, only weak references are kept for bound methods.

This method is can also be used as a decorator:

@cursor.connect("add")
def on_add(sel):
    ...
disconnect(cid)[source]

Disconnect a previously connected callback id.

enabled

Whether clicks are registered for picking and unpicking events.

remove()[source]

Remove all Selections and disconnect all callbacks.

selections

The tuple of current Selections.

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

Create a Cursor for a list of artists or axes.

Parameters:
  • artists_or_axes (Optional[List[Union[Artist, Axes]]]) – All artists in the list and all artists on any of the axes passed in the list are selectable by the constructed Cursor. Defaults to all artists on any of the figures that pyplot is tracking.
  • **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.

The Selection is built from *args, **kwargs.

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.

The Selection is built from *args, **kwargs.

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