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

Chapter 6 - Drawing and Graphics 2.1 / Using Drawing and Graphics in the Newton 2.1 OS

New Graphic Shape Utility Functions

This section defines a few new utility functions.

The FindShape Function

The new *FindShape function has been provided to overcome some of the deficiencies of HitShape. Since changing HitShape would break existing code, this new function has been introduced. HitShape is now a deprecated function, use *FindShape from now on.

This new function differs from HitShape in the following ways:

• Shapes are found from front to back instead of back to front. If two shapes overlap and you call HitShape with a point in their intersection, the backmost shape was returned. *FindShape returns the frontmost shape.
• Support is provided for hit testing resize handles.
• *FindShape takes a style frame as an argument so you can use it the same way you do DrawShape. If you draw a rectangle on the screen with a style frame that moves it 20 pixels to the right, you are probably interested in whether a pen tap is within the rectangle where it is drawn on the screen, not in its original position.
• If a shape has no fill pattern the tap "falls through" and will miss, or hit a shape below it.
• There is "slop" built into the hit testing so taps a few pixels from a shape still hit the shape.
• The new ink and text box shapes are supported.

The GetPointsArrayXY Function

The GetPointsArray function has existed since the Newton 1.0 OS. It accepts a unit, which is passed in to a ViewWordScript, ViewStrokeScript, or ViewGestureScript method, and returns an array of points in that unit. It returns the points in (y,x) order. That is, the first array element is the first point's y coordinate, the second is its x coordinate, the third is the next point's y coordinate, and so on. The new function *GetPointsArrayXY does the same thing, only that the coordinates are in (x,y) order.

The MungeShape Function

The *MungeShape function can flip a shape or rotate it 90û to the right. The MungeBitmap function has existed since Newton 2.0 OS, it similarly flips and rotates bitmaps. The following code example illustrates the use of the *MungeShape function:

 //this is in a ViewDrawScript

local oval := MakeOval (5,5,100,25); //a short and fat oval
:DrawShape(oval, {fillPattern: kRGB_Gray3});

//now draw it tall and skinny on top of the original oval
MungeShape(oval, 'rotateRight, nil);
 :DrawShape(oval, {fillPattern: kRGB_Black, transferMode: modeXor});

The above code generated Figure 6-8 on page 6-20.

Figure 6-8 Overlapping ovals

The GetMaskedPixel Function

*GetMaskedPixel augments the existing function PtInPicture. PtInPicture determines whether a specific point is a black pixel in a black and white bitmap. *GetMaskedPixel returns the value of a pixel in a color picture. This function considers the effect of a mask.