---

HIShape Reference

Overview

HIShape is an abstract shape object that replaces the old QuickDraw region handle. HIShape objects are the preferred way to describe regions in HIView views that use Quartz.

One advantage of HIShape objects is that they can be mutable or immutable. Using immutable (that is, fixed) shapes improves performance because copying it simply requires incrementing the reference count, avoiding the handle-to-handle copies required with the older region handles.

Currently, HIShape objects cannot handle floating point–based shape descriptions. Therefore, any coordinates you specify when defining shapes must end on integer boundaries. The purpose of the shape often dictates whether rounding fractional values up or down will give you the best results. For example, shapes that describe a maximum alllowable area, such as the structure region of a window, should be rounded up (or outward) to the nearest integer. Shapes describing a minimum allowable area, such as the opaque region, should be rounded down (or inward). By default, any fractional coordinate values are truncated.

Typical shapes are rectangular, but you can build more complex shapes by combining them with other shapes using the union, intersection, or difference functions. The Quartz-savvy HITheme APIs also let you obtain shapes for various standard control elements.

In most cases, applications will obtain or set shapes in response to a Carbon event using GetEventParameter or SetEventParameter with the typeHIShapeRef parameter type.

The following functions also take HIShape references as parameters:

• HIViewNewTrackingArea and HIViewChangeTrackingArea, which let you set or change an HIShape-based tracking area in a view (comparable to window tracking regions).

• HIViewSetNeedsDisplayInShape, which is the HIShape-compatible version of HIViewSetNeedsDisplayInRegion.

Except where noted, HIShape functions return only the result codes noErr or paramErr.

HIShape objects are available in Mac OS X version 10.2 and later. However, many of the functions that take HIShape parameters are available only in Mac OS X version 10.4 and later.

Functions by Task

Creating Immutable Shapes

• HIShapeCreateWithQDRgn
• HIShapeCreateWithRect
• HIShapeCreateEmpty
• HIShapeCreateCopy
• HIShapeCreateIntersection
• HIShapeCreateDifference
• HIShapeCreateUnion

Creating Mutable Shapes

• HIShapeCreateMutable
• HIShapeCreateMutableCopy
• HIShapeSetEmpty
• HIShapeIntersect
• HIShapeDifference
• HIShapeUnion
• HIShapeOffset

Querying Shapes

• HIShapeIsEmpty
• HIShapeIsRectangular
• HIShapeContainsPoint

Manipulating Shapes

• HIShapeGetTypeID
• HIShapeGetBounds
• HIShapeIntersectsRect
• HIShapeGetAsQDRgn
• HIShapeReplacePathInCGContext
• HIShapeSetQDClip

Functions

HIShapeContainsPoint

Determines whether a shape contains the given point.

Boolean HIShapeContainsPoint (
   HIShapeRef inShape,
   const CGPoint *inPoint
);

Parameters

inShape

The shape to test.

inPoint

The point to test.

Return Value

True if the shape contains the point, False otherwise.

Discussion

This function is comparable to the old QuickDraw function PtInRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateCopy

Creates an immutable copy of a mutable or immutable shape.

HIShapeRef HIShapeCreateCopy (
   HIShapeRef inShape
);

Parameters

inShape

The shape you want to copy.

Return Value

The newly-created copy.

Discussion

Copying an immutable shape simply increments its reference count. Copying a mutable shape actually duplicates it in memory.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateDifference

Creates an immutable shape that is the difference of two shapes.

HIShapeRef HIShapeCreateDifference (
   HIShapeRef inShape1,
   HIShapeRef inShape2
);

Parameters

inShape1

The first shape.

inShape2

The shape to subtract from the first shape.

Return Value

The newly-created difference shape.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateEmpty

Creates an empty immutable shape.

HIShapeRef HIShapeCreateEmpty (
   void
);

Return Value

The newly-created empty shape.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

HIShape.h

HIShapeCreateIntersection

Creates an immutable shape that is the intersection of two shapes.

HIShapeRef HIShapeCreateIntersection (
   HIShapeRef inShape1,
   HIShapeRef inShape2
);

Parameters

inShape1

An existing shape.

inShape2

Another existing shape.

Return Value

The newly-created intersection shape.

Discussion

If the two shapes do not intersect, the shape returned is empty.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateMutable

Creates an empty mutable shape.

HIMutableShapeRef HIShapeCreateMutable (
   void
);

Return Value

An empty, mutable shape.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateMutableCopy

Creates a mutable copy of an existing shape.

HIMutableShapeRef HIShapeCreateMutableCopy (
   HIShapeRef inOrig
);

Parameters

inOrig

The shape to copy.

Return Value

The newly-created copy.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateUnion

Creates an immutable shape that is the union of two shapes.

HIShapeRef HIShapeCreateUnion (
   HIShapeRef inShape1,
   HIShapeRef inShape2
);

Parameters

inShape1

An existing shape.

inShape2

Another existing shape.

Return Value

The newly-created union shape.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateWithQDRgn

Creates an immutable shape from a QuickDraw region.

HIShapeRef HIShapeCreateWithQDRgn (
   RgnHandle inRgn
);

Parameters

inRgn

The region to convert to an immutable shape.

Return Value

The newly created shape.

Discussion

You can use this function to convert handle-based regions to HIShape objects. However, you should be judicious about how often you convert, as this function does require memory allocation.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeCreateWithRect

Creates an immutable shape from a Quartz rectangle.

HIShapeRef HIShapeCreateWithRect (
   const CGRect *inRect
);

Parameters

inRect

The Quartz-based rectangle to convert.

Return Value

The newly-created shape.

Discussion

This function is comparable to the old QuickDraw function RectRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeDifference

Sets a shape to be the difference of two other shapes.

OSStatus HIShapeDifference (
   HIShapeRef inShape1,
   HIShapeRef inShape2,
   HIMutableShapeRef outResult
);

Parameters

inShape1

The first shape.

inShape2

The shape to subtract from the first.

outResult

The shape to hold the difference of the two shapes. This parameter can be one of the source shapes.

Return Value

A result code.

Discussion

This function is comparable to the old QuickDraw function DiffRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeGetAsQDRgn

Creates a QuickDraw region with the same shape as the specified HIShape.

OSStatus HIShapeGetAsQDRgn (
   HIShapeRef inShape,
   RgnHandle outRgn
);

Parameters

inShape

The shape to convert.

outRgn

A valid region handle. You must obtain this handle by calling NewRgn before calling this function.

Return Value

A result code.

Discussion

You can use this function to create a handle-based region from an HIShape object. This conversion requires memory allocation, so you should convert only when necessary.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeGetBounds

Obtains the bounding rectangle for the given shape.

CGRect * HIShapeGetBounds (
   HIShapeRef inShape,
   CGRect *outRect
);

Parameters

inShape

The shape whose bounds you want to obtain.

inRect

A pointer to the HIRect structure you want filled with the shape bounds.

Return Value

A pointer to the rectangle you passed in the inRect parameter, now set to the shape’s bounding rectangle.

Discussion

The function result is a pointer to the HIRect structure you passed in the inRect parameter.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeGetTypeID

Obtains the Core Foundation type ID for the HIShape class.

CFTypeID HIShapeGetTypeID (
   void
);

Return Value

The type ID for the HIShape class.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeIntersect

Sets a shape to be the intersection of two other shapes.

OSStatus HIShapeIntersect (
   HIShapeRef inShape1,
   HIShapeRef inShape2,
   HIMutableShapeRef outResult
);

Parameters

inShape1

The first shape.

inShape2

The second shape.

outResult

The shape to hold the intersection of the two shapes. This parameter can be one of the source shapes.

Return Value

A result code.

Discussion

This function is comparable to the old QuickDraw function SectRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeIntersectsRect

Determines whether a given shape intersects a given rectangle.

Boolean HIShapeIntersectsRect (
   HIShapeRef inShape,
   const CGRect *inRect
);

Parameters

inShape

The shape to test.

inRect

The rectangle to test against.

Return Value

Returns True if the area of the shape intersects the rectangle, False otherwise.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

HIShape.h

HIShapeIsEmpty

Determines whether a given shape is empty.

Boolean HIShapeIsEmpty (
   HIShapeRef inShape
);

Parameters

inShape

The shape to test.

Return Value

True if the shape’s area is empty, False otherwise.

Discussion

This function is comparable to the old QuickDraw function EmptyRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeIsRectangular

Determines whether a given shape is rectangular.

Boolean HIShapeIsRectangular (
   HIShapeRef inShape
);

Parameters

inShape

The shape to test.

Return Value

True if the shape’s area is rectangular, False otherwise.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeOffset

Moves a shape by a specified offset.

OSStatus HIShapeOffset (
   HIMutableShapeRef inShape,
   CGFloat inDX,
   CGFloat inDY
);

Parameters

inShape

The shape to offset.

inDx

The desired x-coordinate offset.

inDy

The desired y-coordinate offset.

Return Value

A result code.

Discussion

This function is comparable to the old QuickDraw function OffsetRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeReplacePathInCGContext

Make the current path in a graphics context match a shape.

OSStatus HIShapeReplacePathInCGContext (
   HIShapeRef inShape,
   CGContextRef inContext
);

Parameters

inShape

The shape to apply to the path.

inContext

The context to apply the shape to.

Return Value

A result code.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeSetEmpty

Sets the specified mutable shape to be empty.

OSStatus HIShapeSetEmpty (
   HIMutableShapeRef inShape
);

Parameters

inShape

The shape to empty.

Return Value

A result code.

Discussion

This function is comparable to the old QuickDraw function SetEmptyRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIShapeSetQDClip

Sets the clip region in the current QuickDraw port to be the specified shape.

OSStatus HIShapeSetQDClip (
   HIShapeRef inShape,
   CGrafPtr inPort
);

Parameters

inShape

The shape to apply to the clip region.

inPort

The clip region to apply the shape to.

Return Value

A result code. If HIShapeSetQDClip cannot allocate a QuickDraw region, it returns memFullErr.

Availability

• Available in Mac OS X v10.2 and later.
• Not available to 64-bit applications.

Declared In

HIShape.h

HIShapeUnion

Sets a shape to be the union of two other shapes.

OSStatus HIShapeUnion (
   HIShapeRef inShape1,
   HIShapeRef inShape2,
   HIMutableShapeRef outResult
);

Parameters

inShape1

An existing shape.

inShape2

Another existing shape.

outResult

The shape to hold the union of the two shapes. This parameter can be one of the source shapes.

Return Value

A result code.

Discussion

This function is comparable to the old QuickDraw function UnionRgn.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

Data Types

HIShapeRef

Defines a shape object.

typedef const struct __HIShape *HIShapeRef;

Discussion

The structure pointed to by this reference is opaque.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

HIMutableShapeRef

Defines a mutable shape object.

typedef struct __HIShape *HIMutableShapeRef;

Discussion

The structure pointed to by this reference is opaque.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

HIShape.h

---