Document Artist.get_cursor_data - #12427

Similar to monkey-patching .format_coords (as in the image_zcoord example) a user might also monkey-patch either of get_cursor_data and format_cursor_data. This is actually a bit harder to understand, but allows more flexibility. E.g. the event passed to get_cursor_data carries more information than just a position, which a user can utilize for their puurposes. There is hence value in keeping those methods public.

The actual changes here look fine.

@ImportanceOfBeingErnest Maybe a bit beyond this PR, but for monkey-patching we must also specify what event is. Otherwise, the user cannot know what to do in the patched function.

I'm not clear about this myself. Is this just called with MouseEvent or can there be other event types? Do we do this in practice in the current version, or is it just possible that we call it with other events in the future. These things are important to specify if we really want this to be public API. I don't feel competent to judge this and therefore was considering to make this private to not make any false promises.

Do we know if there are really people using this API?

Anyone knows something about the event?

#12427 (comment)

Do we know if there are really people using this API?

From now on, everyone running the below code, is using this 😁

import matplotlib.pyplot as plt
from matplotlib.lines import Line2D

def strlinedata(self, event):
    lines = []
    if event.inaxes:
        for line in event.inaxes.lines:
            if line.contains(event)[0]:
                lines.append(line)
    if lines:
        return [line.get_label() for line in lines]
    
def fmtdata(self, data):
    return data.__repr__()

Line2D.mouseover = True
Line2D.get_cursor_data = strlinedata
Line2D.format_cursor_data = fmtdata


fig, ax = plt.subplots()
ax.plot([1,3,2], label="Label 1")
ax.plot([1,2,1], label="Label 2")

plt.show()

Anyone knows something about the event?

Implicitely, it needs to be a MouseEvent. This is because mouse_move() calls Artist.contains with the event given to it for every artist that has the mousemove attribute.
The signature for Artist.contains is

def contains(self, mouseevent):
        """Test whether the artist contains the mouse event."""