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.
