# Hit Testing

There are several situations which require finding a figure for a mouse location. For example, determining which tooltip to display when the mouse pauses on top of a figure canvas. Another example is interactive graphical applications, which must interpret dragging one figure on top of another.

There are four methods available on IFigure which perform hit testing, three of which are actually just convenience methods which call the fourth.

- `findFigureAt(int x, int y)`- finds the top-most figure for the given x and y coordinate
- `findFigureAt(Point p)` - similar to above, except takes a Point instead of an int
- `findFigureAtExcluding(int x, int y, Collection exclude)` - finds the top-most figure for the given coordinates that is not in the exclusion set or contained by a figure in the exclusion set. This is used for ignoring a figure being dragged, or for ignoring transparent layers or figures which are not involved in an interaction.

- `findFigureAt(int x, int y, TreeSearch)` - All of the above methods call this method. TreeSearch is a helper that is used to quickly prune branches which should not be searched, and to accept the final candidate figure.

Hit testing must be done exactly the same way as painting. Clipping and coordinate changes must be duplicated in both. As an optimizations, branches of the figure composition tree are pruned by calling `containsPoint()`. If a figure does not contain the location, it returns NULL and does not search its children. By default, all figures are considered to be the rectangular region defined by their bounds, regardless of how or if they paint. This can be overridden as it is in Polyline, Ellipse, and other figures.