/*
File: HIShape.h
Contains: Generic Abstract Shape API
Version: QuickTime 7.3
Copyright: (c) 2007 (c) 2001 by Apple Computer, Inc., all rights reserved.
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
*/
#ifndef __HISHAPE__
#define __HISHAPE__
#ifndef __APPLICATIONSERVICES__
#include <ApplicationServices.h>
#endif
#ifndef __CARBONEVENTS__
#include <CarbonEvents.h>
#endif
#if PRAGMA_ONCE
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if PRAGMA_IMPORT
#pragma import on
#endif
/*
* HIShape
*
* Discussion:
* HIShape is an abstract shape object for use with some of the
* HIToolbox APIs. It is designed as a replacement for RgnHandles
* (though it is currently implemented in terms of them at the time
* of this writing). This abstraction will allow us to avoid using
* QD types in our APIs, particularly in HIView.
*
* One of the biggest benefits of HIShape is that we have mutable
* and immutable variants. This means that immutable shapes can be
* created and passed around and 'copied' very quickly, since they
* are actually refcounted when copied. This avoids needing to do
* the handle-to-handle copies that occur right now with
* RgnHandle-based APIs.
*/
typedef const struct __HIShape* HIShapeRef;
typedef struct __HIShape* HIMutableShapeRef;
/*
* HIShapeGetTypeID()
*
* Discussion:
* Returns the CF type ID for the HIShape class.
*
* Result:
* A CF type ID.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( CFTypeID )
HIShapeGetTypeID(void);
/*======================================================================================*/
/* IMMUTABLE FUNCTIONS */
/*======================================================================================*/
/*
* HIShapeCreateWithQDRgn()
*
* Discussion:
* Creates an immutable shape based on an existing Quickdraw region
* handle.
*
* Parameters:
*
* inRgn:
* The Quickdraw region from which to create the HIShape.
*
* Result:
* An immutable HIShape reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIShapeRef )
HIShapeCreateWithQDRgn(RgnHandle inRgn);
/*
* HIShapeCreateWithRect()
*
* Discussion:
* Creates an immutable, rectangular shape based on a given
* rectangle.
*
* Parameters:
*
* inRect:
* The HIRect from which to create the resulting shape.
*
* Result:
* An immutable HIShape reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIShapeRef )
HIShapeCreateWithRect(const HIRect * inRect);
/*
* HIShapeCreateCopy()
*
* Discussion:
* Creates an immutable copy of a mutable or immutable HIShape.
*
* Parameters:
*
* inShape:
* The existing HIShapeRef you wish to copy.
*
* Result:
* An immutable HIShape reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIShapeRef )
HIShapeCreateCopy(HIShapeRef inShape);
/*
* HIShapeCreateIntersection()
*
* Discussion:
* Creates a new immutable shape which is the intersection of two
* others.
*
* Parameters:
*
* inShape1:
* An existing HIShapeRef.
*
* inShape2:
* An existing HIShapeRef.
*
* Result:
* A new immutable HIShapeRef.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIShapeRef )
HIShapeCreateIntersection(
HIShapeRef inShape1,
HIShapeRef inShape2);
/*
* HIShapeCreateDifference()
*
* Discussion:
* Creates a new immutable shape which is the difference of two
* others. The second shape is subtracted from the first.
*
* Parameters:
*
* inShape1:
* An existing HIShapeRef.
*
* inShape2:
* An existing HIShapeRef.
*
* Result:
* A new immutable HIShapeRef.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIShapeRef )
HIShapeCreateDifference(
HIShapeRef inShape1,
HIShapeRef inShape2);
/*
* HIShapeCreateUnion()
*
* Discussion:
* Creates a new immutable shape which is the union of two others.
*
* Parameters:
*
* inShape1:
* An existing HIShapeRef.
*
* inShape2:
* An existing HIShapeRef.
*
* Result:
* A new immutable HIShapeRef.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIShapeRef )
HIShapeCreateUnion(
HIShapeRef inShape1,
HIShapeRef inShape2);
/*
* HIShapeIsEmpty()
*
* Discussion:
* Returns true if the given HIShapeRef is empty, i.e. its area is
* empty.
*
* Parameters:
*
* inShape:
* The existing HIShapeRef you wish to test.
*
* Result:
* A boolean result.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( Boolean )
HIShapeIsEmpty(HIShapeRef inShape);
/*
* HIShapeIsRectangular()
*
* Discussion:
* Returns true if the given HIShapeRef is rectangular.
*
* Parameters:
*
* inShape:
* The existing HIShapeRef you wish to test.
*
* Result:
* A boolean result.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( Boolean )
HIShapeIsRectangular(HIShapeRef inShape);
/*
* HIShapeContainsPoint()
*
* Discussion:
* Returns true if the given HIShapeRef contains the point passed in.
*
* Parameters:
*
* inShape:
* An existing HIShapeRef.
*
* inPoint:
* The point to check.
*
* Result:
* A boolean result.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( Boolean )
HIShapeContainsPoint(
HIShapeRef inShape,
const HIPoint * inPoint);
/*
* HIShapeGetBounds()
*
* Discussion:
* Returns the bounding rectangle of a given HIShapeRef.
*
* Parameters:
*
* inShape:
* An existing HIShapeRef.
*
* outRect:
* Receives the bounding rectangle.
*
* Result:
* A pointer to the rectangle you passed in, for convenience.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIRect * )
HIShapeGetBounds(
HIShapeRef inShape,
HIRect * outRect);
/*
* HIShapeGetAsQDRgn()
*
* Discussion:
* Changes a given Quickdraw region handle to have the same shape as
* a given HIShapeRef. Essentially you are converting an HIShapeRef
* into a RgnHandle. This conversion may lose fidelity depending on
* how the shape was created originally.
*
* Parameters:
*
* inShape:
* An existing HIShapeRef.
*
* outRgn:
* An existing region to change.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeGetAsQDRgn(
HIShapeRef inShape,
RgnHandle outRgn);
/*
* HIShapeReplacePathInCGContext()
*
* Discussion:
* Given an HIShapeRef and a CGContextRef, make the current path in
* the context represent the shape. You might use this to clip to a
* shape, for example. You could call this function and then
* immediately call CGContextClip.
*
* Parameters:
*
* inShape:
* An existing HIShapeRef.
*
* inContext:
* The context to apply the shape to.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeReplacePathInCGContext(
HIShapeRef inShape,
CGContextRef inContext);
/*
* HIShapeSetQDClip()
*
* Discussion:
* Given an HIShapeRef and a Quickdraw port, set the current clip in
* the port to the shape.
*
* Parameters:
*
* inShape:
* An existing HIShapeRef.
*
* inPort:
* The port to set the clip for.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeSetQDClip(
HIShapeRef inShape,
CGrafPtr inPort);
/*======================================================================================*/
/* MUTABLE FUNCTIONS */
/*======================================================================================*/
/*
* HIShapeCreateMutable()
*
* Discussion:
* Creates a new, mutable, empty shape.
*
* Result:
* A mutable shape reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIMutableShapeRef )
HIShapeCreateMutable(void);
/*
* HIShapeCreateMutableCopy()
*
* Discussion:
* Given an existing HIShapeRef, creates a new mutable copy.
*
* Parameters:
*
* inOrig:
* The shape to copy.
*
* Result:
* A mutable shape reference.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( HIMutableShapeRef )
HIShapeCreateMutableCopy(HIShapeRef inOrig);
/*
* HIShapeSetEmpty()
*
* Discussion:
* Sets a mutable shape to be an empty shape.
*
* Parameters:
*
* inShape:
* The shape to empty.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeSetEmpty(HIMutableShapeRef inShape);
/*
* HIShapeIntersect()
*
* Discussion:
* Takes two shapes and sets a third to be their intersection.
*
* Parameters:
*
* inShape1:
* The first shape.
*
* inShape2:
* The second shape.
*
* outResult:
* The shape to receive the result of the intersection. This can
* be one of the source shapes.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeIntersect(
HIShapeRef inShape1,
HIShapeRef inShape2,
HIMutableShapeRef outResult);
/*
* HIShapeDifference()
*
* Discussion:
* Takes two shapes and sets a third to be their difference. The
* second shape is subtracted from the first.
*
* Parameters:
*
* inShape1:
* The first shape.
*
* inShape2:
* The second shape.
*
* outResult:
* The shape to receive the result of the intersection. This can
* be one of the source shapes.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeDifference(
HIShapeRef inShape1,
HIShapeRef inShape2,
HIMutableShapeRef outResult);
/*
* HIShapeUnion()
*
* Discussion:
* Takes two shapes and sets a third to be their union.
*
* Parameters:
*
* inShape1:
* The first shape.
*
* inShape2:
* The second shape.
*
* outResult:
* The shape to receive the result of the union. This can be one
* of the source shapes.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeUnion(
HIShapeRef inShape1,
HIShapeRef inShape2,
HIMutableShapeRef outResult);
/*
* HIShapeOffset()
*
* Discussion:
* Offsets a shape by some delta.
*
* Parameters:
*
* inShape:
* The shape to offset.
*
* inDX:
* The delta to move the shape on the X axis.
*
* inDY:
* The delta to move the shape on the Y axis.
*
* Result:
* An operating system status code.
*
* Availability:
* Non-Carbon CFM: not available
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
* Mac OS X: in version 10.2 and later
*/
EXTERN_API_C( OSStatus )
HIShapeOffset(
HIMutableShapeRef inShape,
float inDX,
float inDY);
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
#ifdef __cplusplus
}
#endif
#endif /* __HISHAPE__ */