FindShape

Newton Developer Technical Information: Newton Programmer's Guide: 2.1 OS Addendum /

Chapter 6 - Drawing and Graphics 2.1 / Drawing and Graphics Reference

FindShape
FindShape(shape,x,y,style)
Indicates whether the point (x,y) lies in the specified shape if it were drawn in the specified style.

shape
The shape or array of shapes to test.

x
The x coordinate of the point to be tested, in local (view) coordinates. Note that GetPoints returns global coordinates.

y
The y coordinate of the point to be tested, in local (view) coordinates. Note that GetPoints returns global coordinates.

style
A style frame to be applied to shape.

return value
Returns nil if no shape is found, otherwise a frame with the following slots:
path If shape is a single shape, then the Boolean true. If shape is an array of shapes, then a path expression to the shape within the array.
vertex If the hit was not on a resize handle, this slot is set to nil. If a handle was hit, this slot contains an integer with the following meaning:
0 = top-left corner
1 = top-right corner
2 = bottom-right corner
3 = bottom-left corner

DISCUSSION
This function replaces the HitShape function. While HitShape is still defined in the ROM for compatibility reasons, you should use *FindShape from now on.
The shape and style parameters are intended to be used in the same manner as in the DrawShape method. Style frames within a shape array in the shape parameter are also taken into effect. This allows you to use the same code to create shapes and style frames in both your ViewDrawScript (to pass to DrawShape) as well as in your ViewClickScript (or wherever you call *FindShape from).
More than one shape in a shape array could encompass a point. In this case the frontmost shape is returned. The frontmost shape is the one in a later position in the shape array.
If a shape has no fill pattern, the hit "falls through" and will miss, or hit a shape below it. Also, there is "slop" built into the hit testing; taps a few pixels from a shape still hit the shape.