Add inaxes method to FigureCanvas to check whether point is in an axes.

[lkjell]

Add inaxes method to FigureCanvas to check whether point is in an axes.
Return the top-most axes if found, else None.

PR Summary

An alternative way to get an axes given (x,y) coordinate is to create a LocationEvent and use the inaxes attribute. However, instantiate LocationEvent may trigger axes_enter_event and axes_leave_event, which is not one often would like to do. With this method a new way to find the axes without triggering axes_enter_event and axes_leave_event.

From issue #9821.

PR Checklist

• Has Pytest style unit tests
• [x ] Code is PEP 8 compliant
• New features are documented, with examples if plot related
• [x ] Documentation is sphinx and numpydoc compliant
• [x ] Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

[anntzer]

As noted in #9821 I'd rather 1. make Artist.contains be able to take xy input + 2. expose cbook._topmost_artist as public API, which should together provide a much more general solution.

In order to disambiguate whether xy is in figure or in axes or in data coordinates, we could e.g. fiddle with kwargs to support

ax.contains(event)
ax.contains(figure_coords=(x, y))
ax.contains(axes_coords=(x, y))
ax.contains(data_coords=(x, y))

[lkjell]

Problem is how should a user know if there exist a topmost artist method? Heck everything can be done with artist.contains_points. And do some transformasjon between coordinates. Thus the only thing that is really needed is just to expose cbook._topmost_artist.

[lkjell]

In any cases a specific method is not mutually exclusive with general case. I believe for new user which is not matplotlib guru to find this method useful.

[anntzer]

"How does the user know about topmost_artist" and "how does the user know about inaxes" are essentially the same problem -- discoverability of rarely used functions. I'd rather document a more widely useable function (topmost_artist), possibly with some examples in the docstring that show how the function can be used to solve the inaxes problem, rather than add yet another very specialized tool.

[lkjell]

No it is two different problems. If you have an issue related to figure you go into the Figure class and look for its method. You do not go and look in artist (assume you are putting it there). The inaxes method is specialized method because it does what it should do. If you really want to find it usage then just use it in LocationEvent.

[anntzer]

You probably don't want to lose the mouse-grabbing effect.

[anntzer]

My point is that this has in fact nothing to do with axes and figures: what you want to know is rather what artist (if any), among a list of artists, is the topmost at a point in the canvas... (and I am all for documentation that makes {contains + topmost_artist} more discoverable).
In any case I'll let other devs chime in, as I believe I have made my point.

[lkjell]

Just because you do not find its usage I just used it in LocationEvent.

[tacaswell]

For consistency we probably should use _topmost_artist here (so if we ever need to change that logic we can do it exactly once).

[tacaswell]

@anntzer Instead of having a zoo of kwargs, we probably should follow the pattern of taking a transform.

@lkjell contains_points is a Path method not an artist method, but you point stands. From a library point of view we have to sort out what makes sense to add as methods and what makes sense to leave as tools for users to implement what they need and where to put it.

This method may make more sense on CanvasBase (as that is the layer that definitely knows about screen coordinates) rather than on Figure (in your example in #9821 that is where you put it).

[anntzer]

@tacaswell your point of adding a transform kwarg to contains (for example) is well taken.
I really do not believe this method should be added, so I am going to reject the changes. Other reviewers should feel free to dismiss this review if they do not consider my arguments convincing.

[tacaswell]

I think this is a useful thing to have factored out and exposed and is a reasonable implementation.

[jklymak]

This looks good to me. Needs a rebase

[lkjell]

@tacaswell and @jklymak since there are 2 approvals it can be merged now?

[jklymak]

Merging over @anntzer disapproval. This tool doesn't have a lot of complicated machinery associated with it, and seems like it is a nice shortcut. I agree that we don't want to have a bunch of duplicated methods but in the absence of the work noted above exposing the API, this seems like a harmless stopgap.

[jklymak]

This broke the build, so suggesting we revert for now. @lkjell if you care to rebase and figure out what broke, that would be fine...