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
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
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.