PR summary

This PR addresses and closes Issue #30944 that I posted earlier. In short, returning more details from the Line2D.contains() hit test could eliminate additional computational needs during time-constrained mouse events. Specifically, the PR adds 'is_vert' boolean array item to the details output dict. This item has the same size as the existing 'ind' item and its element indicates whether the corresponding 'ind' element. Having 'is_vert' is handy when the UI requires a different action when user click on a vertex or on an edge. While this check can be done by user later, Line2D.contains() already performs this test internally (via lines.segment_hits() function). So, why not eliminate the redundant geometric computations.

This PR implements this change by minimally touching lines.Line2D.contains() and lines.segment_hits() functions without breaking their backward compatibility:

• lines.segment_hits() returns the number of vertex hits as an additional int value. This value is only returned if the optional return_is_vert boolean argument is set to True.
• Given this vertex hit count, lines.Line2D.contains() composes the is_vert array and adds it to its details return dict.

Usage example:

from matplotlib import pyplot as plt

fig, ax = plt.subplots()
line = ax.plot([0,1], [0,1], 'o-')[0]

def on_click(event):

    hit, details = line.contains(event)

    if hit:
        if details['is_vert'][0]:
            print('grab and move only the clicked vertex')
        else:
            print('move the line as a whole without changing shape')

plt.connect('button_press_event', on_click)

plt.show()

I have also modified the pick_event_demo.py in galleries/example/event_handling to demonstrate the new feature.

Documentation and docstrings have been updated to best of my ability. The docstring of lines.segment_hits() is not a full-fledged one. So, I just expanded it in the same style.

PR checklist

• "closes [ENH]: Line2D.contains() to return additional details #30944" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines