One of the key advantages of using an offscreen graphics ports is that it allows you to improve on-screen drawing speed and visual smoothness. For example, suppose your application draws multiple graphics objects in a window and then needs to update part of that window. If your image is very complex, your application can copy it from an offscreen graphics world to the screen faster than it can repeat all of the steps necessary to draw the image on-screen. At the same time, the inelegant visual effects associated with the time-consuming drawing a large number of separate objects are avoided.

Creating an Offscreen Graphics World

     typedef CGrafPtr GWorldPtr;

• Provides your application with the default behaviour of NewGWorld.

• Allows QuickDraw to optimise the CopyBits, CopyMask, and CopyDeepMask functions used to copy the image into the window's port rectangle.

SetGWorld takes two parameters (port and gdh). If the port parameter is of type CGrafPtr, the current port is set to the port specified in the port parameter and the current device is set to the device specified in the gdh parameter. If the port parameter is of type GWorldPtr, the current port is set to the port specified in the port parameter, the gdh parameter is ignored, and the current device is set to the device attached to the offscreen graphics world.

Preparing to Draw Into an Offscreen Graphics World

LockPixels prevents the base address of an offscreen pixel image from being moved while you draw into it or copy from it. If the base address for an offscreen pixel image has not been purged by the Memory Manager, or if its base address is not purgeable, LockPixels returns true. If LockPixels returns false, your application should either call the UpdateGWorld function to reallocate the offscreen pixel image and then reconstruct it, or draw directly into an onscreen graphics port.

As a related matter, note that the baseAddr field of the PixMap structure for an offscreen graphics world contains a handle, whereas the baseAddr field for an onscreen pixel map contains a pointer. You must use the GetPixBaseAddr function to obtain a pointer to the PixMap structure for an offscreen graphics world.

Copying an Offscreen Image into a Window

The image is copied from the offscreen graphics world into the window using CopyBits (or, if masking is required, CopyMask or CopyDeepMask). Specify the offscreen graphics world as the source image for CopyBits and specify the window as its destination. Note that CopyBits, CopyMask and CopyDeepMask expect their source and destination parameters to be pointers to bit maps, not pixel maps. Accordingly, you must coerce the offscreen graphic's world's GWorldPtr data type to a data structure of type GrafPtr. Similarly, whenever a colour graphics port is your destination, you must coerce the window's CGrafPtr data type to data type GrafPtr.

As long as you are drawing into an offscreen graphics world or copying an image from it, you must leave its pixel image locked. When you are finished drawing into, and copying from, an offscreen graphics world, call UnlockPixels. Calling UnlockPixels will assist in preventing heap fragmentation.

Updating an Offscreen Graphics World

When you use OpenCPicture to begin defining a picture, QuickDraw collects your subsequent drawing commands in a data structure of type Picture. By using DrawPicture, you can draw onscreen the picture defined by the instructions stored in the Picture structure.

Picture Format

The Picture Structure

     struct Picture
     {
       short  picSize;   // For a version 1 picture: its size.
       Rect   picFrame;  // Bounding rectangle for the picture.
     };
     typedef struct Picture Picture;
     typedef Picture *PicPtr;
     typedef PicPtr *PicHandle;

Opcodes: Drawing Commands and Picture Comments

In addition to compact drawing commands, opcodes can also specify picture comments, which are created using PicComment. A picture comment contains data or commands for special processing by output devices, such as PostScript printers. If your application requires capability beyond that provided by QuickDraw drawing functions, PicComment allows your application to pass data or commands direct to the output device.

You typically use QuickDraw commands when drawing to the screen and picture comments to include special drawing commands for printers only.

'PICT' Files, 'PICT' Resources, and 'PICT' Scrap Format

See Chapter 18 - Scrap.

A picture can be stored as a 'PICT' resource in the resource fork of any file type. A picture can also be stored in the data fork of a file of type 'PICT'. The data fork of a 'PICT' file contains a 512-byte header that applications can use for their own purposes.

For each application, the Scrap Manager maintains a storage area to hold the last data cut or copied by the user. The area that is available to your application for this purpose is called the scrap. All applications that support copy-and-paste operations read data from, and write data to, the scrap. The 'PICT' scrap format is one of two standard scrap formats. (The other is 'TEXT'.)

The Picture Utilities

The Picture utilities allow you to gather colour, comment, font, resolution, and other information about pictures. You might use the Picture Utilities, for example, to determine the 256 most-used colours in a picture, and then use the Palette Manager to make those colours available for the window in which the application needs to draw the picture.

Creating Pictures

You pass information to OpenCPicture in the form of an OpenCPicParams structure:

     struct OpenCPicParams
     {
       Rect   srcRect;    // Optimal bounding rectangle.
       Fixed  hRes;       // Best horizontal resolution.
       Fixed  vRes;       // Best vertical resolution.
       short  version;    // Set to -2.
       short  reserved1;  // (Reserved.  Set to 0.)
       long   reserved2;  // (Reserved.  Set to 0.)
     };
     typedef struct OpenCPicParams OpenCPicParams;

The demonstration program at Chapter 16 - Files shows how to read pictures from, and save pictures to, files of type 'PICT'.

When the picture is retrieved, you should call DrawPicture to draw the picture. The second parameter taken by DrawPicture is the destination rectangle, which should be specified in coordinates local to the current graphics port. DrawPicture shrinks or stretches the picture as necessary to make it fit into this rectangle.

When you are finished using a picture stored as a 'PICT' resource, you should use the resource Manager function ReleaseResource to release its memory.

Saving Pictures

Cursor Visibility

• To indicate that the user is over a certain area of the screen. For example, when the cursor is in the menu bar, it should usually have an arrow shape. When the user moves the cursor over a text document, your application should change the cursor to the I-beam shape.

• To provide feedback about the status of the computer system. For example, if an operation will take a second or two, you should provide feedback to the user by changing the cursor to the wristwatch cursor (see Fig 2). If the operation takes several seconds and the user can do nothing in your application but stop the operation, wait until it is completed, or switch to another application, you should display an animated cursor (see below).

  If the operation takes longer than several seconds, you should display a dialog box with a progress indicator. (See Chapter 23 - Miscellany.)

The Mac OS 8.0 and later System file contains additional 'CURS' resources. The Mac OS 8.5 and later System file contains three 'crsr' resources. The following are the resource IDs for the additional cursors as shown as Fig 3:

Custom 'CURS' and 'crsr' Resources

To change cursor shape, your application must get a handle to the relevant cursor (either a custom cursor or one of the system cursors shown at Fig 2 and 3) by specifying its resource ID in a call to GetCursor or GetCCursor. GetCursor returns a handle to a Cursor structure. GetCCursor returns a handle to a CCrsr structure. The address of the Cursor or CCrsr structure is then used in a call to SetCursor or SetCCursor to change the cursor shape.

Changing Cursor Shape � Theme-Compliant Methodology

Changing Cursor Shape in Response to Mouse-Moved Events

Note that your application may also have to accommodate the cursor shape changing requirements of modeless dialog boxes with edit text field items.as well as its main windows.

Changing Cursor Shape in Response to Resume Events

Non-Theme-Compliant Methodology

Creating the Animated Cursor

• If you do not intend to use the system-supplied 'acur' and associated 'CURS' resources:

  • Create a series of 'CURS' resources that make up the "frames" of the animation.

  • Create an 'acur' resource.

• Load the 'acur' resource into an application-defined structure which replicates the structure of an 'acur' resource, for example:

       typedef struct
       {
         short       numberOfFrames;
         short       whichFrame;
         CursHandle  frame[];
       } animCurs, *animCursPtr, **animCursHandle;
  
  

• Load the 'CURS' resources using GetCursor and assign handles to the resulting Cursor structures to the elements of the frame field.

• At the desired interval, call SetCursor to display each cursor, that is, each "frame", in rapid succession, returning to the first frame after the last frame has been displayed.

The provision of a family of icon types for each desktop object, rather than just one icon type, enables the Finder to automatically select the appropriate family member to display depending on the icon size specified by the user and the bit depth of the display device. Chapter 9 described the components of an icon family used by the Finder as follows:

Creating Icon Family Resources Using Resorcerer

The four icon sizes are mini, small, large, and huge, the latter being a new size of 48 by 48 pixels. Four colour depths (1-bit, 4-bit, 8-bit, and 32-bit) and two kind of masks (1-bit and 8-bit) are supported. The deep (8 bit) mask means that masks can have 256 different levels of transparency.

Icon Services checks for an 'icns' resource of the specified ID before it checks for the older resource types ('ics#', 'icl4', 'icm8', etc.) of the same ID. If an 'icns' resource is found, Icon Services obtains all icon data exclusively from that resource.

As of Version 2.2, Resorcerer had no pixel editor for 'icns' resources. However, a command available in the Icon Family editor will take all icons currently being shown and build an 'icns' resource with the same resource ID as those icons. (Choose Build/Update 'icns' from the IconFamily menu.)

Other Icons - Icons, Colour Icons and Small Icons

Typically, only the Finder and the Standard File Package use small icons.

Icons in Windows, Menus, and Alert and Dialog Boxes

• Create the icon resource with a resource ID between 257 and 511. Subtract 256 from the resource ID to get a value called the icon number. Specify the icon number in the Icon field of the menu item definition.

• For an icon ('ICON'), specify 0x1D in the keyboard equivalent field of the menu item definition to indicate to the Menu Manager that the icon should be reduced to fit into a 16-by-16 pixel rectangle. Otherwise, specify a value of 0x00, or a value greater than 0x20, in the keyboard equivalent field to cause the Menu Manager to expand the item's rectangle so as to display the icon at its normal 32-by-32 pixel size. (A value greater than 0x20 in the keyboard equivalent field specifies the item's Command-key equivalent.)

• For a colour icon ('cicn'), specify 0x00 or a value greater than 0x20 in the keyboard equivalent field. The Menu Manager automatically enlarges the enclosing rectangle of the menu item according to the rectangle specified in the 'cicn' resource. (Colour icons, unlike icons, can be any height or width between 8 and 64 pixels.)

• For a small icon ('SICN'), specify 0x1E in the keyboard equivalent field. This indicates that the item has an icon defined by a 'SICN' resource. The Menu Manager plots the icon in a 16-by-16 pixel rectangle.

Note that, for the Apple and Application menus, the Menu Manager either automatically reduces the icon to fit within the enclosing rectangle of the menu item or uses the appropriate icon from the application's icon family, such as the 'icl8' resource, if one is available.

Icons in Alert and Dialog Boxes

To display the icon alone, the procedure is to define an item of type Icon and provide the resource ID of the icon in the item list ('DITL') resource for the dialog. This will cause the Dialog Manager to automatically display the icon whenever you display the alert or dialog box using Dialog Manager functions.

To display the icon within an image well, include an image well control in the alert or dialog box's item list and assign the resource ID of the icon to the control's minimum value field.

If you provide a colour icon ('cicn') resource with the same resource ID as an icon ('ICON') resource, the Dialog Manager displays the colour icon instead of the black-and-white icon.

Ordinarily, you would use the Alert function (which does not automatically draw a system-supplied alert icon in the alert box), or the StandardAlert function with kAlertPlainAlert passed in the inAlertType parameter, when you wish to display an alert containing your own icon (for example, in your application's About... alert box). If you invoke an alert box using the NoteAlert, CautionAlert, or StopAlert functions, or with the StandardAlert function with an alert type constant of other than kAlertPlainAlert passed in the inAlertType parameter, the Dialog Manager draws the system-supplied black-and-white icon as well as your icon. Since your icon is drawn last, you can obscure the system-suppled icon by positioning your icon at the same coordinates.

Drawing and Manipulating Icons

• You wish to draw icons in your application's windows.

• You wish to draw icons which are not recognised by the Menu Manager and the Dialog Manager in, respectively, menu items and dialog boxes.

Each icon in an icon family shares the same resource ID as other icons in the family but has its own resource type identifying the icon data it contains.

Icon Suites

When you create an icon suite from icon family resources, the associated resource file should remain open while you use Icon Utilities functions.

Icon Cache

Icon Stretching and Shrinking

Variables of type IconAlignmentType and IconTransformType should be declared and assigned values representing alignment and transform requirements. Constants, such as kAlignAbsoluteCenter and kTransformNone, are available to specify alignment and transform requirements.

Getting an Icon Suite and Drawing One of Its Icons

To draw resources of resource type 'ICON', 'cicn', and 'SICN' in your application's windows, you use the following functions:

The functions in this list ending in Handle allow you to specify alignment and transforms for the icon.

Manipulating Icons

The Icon Utilities also include functions which allow you to perform an action on one or more icons in an icon suite and to perform hit testing on icons.

Main Constants, Data Types and Functions - Offscreen Graphics Worlds

pixPurgeBit         = 0   Set to make base address for offscreen pixel image purgeable.
noNewDeviceBit      = 1   Set to not create a new GDevice structure for offscreen world.
pixelsPurgeableBit  = 6   Set to make base address for pixel image purgeable.
pixelsLockedBit     = 7   Set to lock base address for offscreen pixel image.

typedef CGrafPtr  GWorldPtr;
typedef unsigned long  GWorldFlags;

QDErr        NewGWorld(GWorldPtr *offscreenGWorld,short PixelDepth,
             const Rect *boundsRect,CTabHandle cTable,GDHandle aGDevice,
             GWorldFlags flags);
GWorldFlags  UpdateGWorld(GWorldPtr *offscreenGWorld,short pixelDepth,
             const Rect *boundsRect,CTabHandle cTable,GDHandle aGDevice,
             GWorldFlags flags);
void         DisposeGWorld(GWorldPtr offscreenGWorld);

void  GetGWorld(CGrafPtr *port,GDHandle *gdh);
void  SetGWorld(CGrafPtr port,GDHandle gdh);

PixMapHandle  GetGWorldPixMap(GWorldPtr offscreenGWorld);
Boolean       LockPixels(PixMapHandle pm);
void          UnlockPixels(PixMapHandle pm);
void          AllowPurgePixels(PixMapHandle pm);
void          NoPurgePixels(PixMapHandle pm);
GWorldFlags   GetPixelsState(PixMapHandle pm);
void          SetPixelsState(PixMapHandle pm,GWorldFlags state);
Ptr           GetPixBaseAddr(PixMapHandle pm);
Boolean       PixMap32Bit(PixMapHandle pmHandle);

returnColorTable       = 0x0001   Return a ColorTable structure.
returnPalette          = 0x0002   Return a Palette structure.
recordComments         = 0x0004   Return comment information.
recordFontInfo         = 0x0008   Return font information.
suppressBlackAndWhite  = 0x0010   Do not include black and white.

systemMethod   = 0   System color pick method.
popularMethod  = 1   Most popular set of colors.
medianMethod   = 2   A good average mix of colors.

struct Picture
{
  short  picSize;  // For a version 1 picture: its size.
  Rect  picFrame;  // Bounding rectangle for the picture
};
typedef struct Picture Picture;
typedef Picture *PicPtr;
typedef PicPtr *PicHandle;

struct OpenCPicParams
{
  Rect   srcRect;     // Optimal bounding rectangle.
  Fixed  hRes;        // Best horizontal resolution.
  Fixed  vRes;        // Best vertical resolution.
  short  version;     // Set to -2
  short  reserved1;   // (Reserved.  Set to 0.)
  long   reserved2;   // (Reserved.  Set to 0.)
};
typedef struct OpenCPicParams OpenCPicParams;

struct  PictInfo
{
  short          version;         // This is always zero, for now.
  long           uniqueColors;    // Number of actual colors in picture(s)/pixmap(s).
  PaletteHandle  thePalette;      // Handle to the palette information.
  CTabHandle     theColorTable;   // Handle to the color table.
  Fixed          hRes;            // Maximum horizontal resolution for all pixmaps.
  Fixed          vRes;            // Maximum vertical resolution for all pixmaps.
  short          depth;           // Maximum depth for all the pixmaps (in picture).
  Rect           sourceRect;      // Picture frame rectangle (contains entire picture).
  long           textCount;       // Total number of text strings in the picture.
  long           lineCount;       // Total number of lines in the picture.
  long           rectCount;       // Total number of rectangles in the picture.
  long           rRectCount;      // Total number of round rectangles in the picture.
  long           ovalCount;       // Total number of ovals in the picture.
  long           arcCount;        // Total number of arcs in the picture.
  long           polyCount;       // Total number of polygons in the picture.
  long           regionCount;     // Total number of regions in the picture.
  long           bitMapCount;     // Total number of bitmaps in the picture.
  long           pixMapCount;     // Total number of pixmaps in the picture.
  long           commentCount;    // Total number of comments in the picture.
  long           uniqueComments;  // The number of unique comments in the picture.
  CommentSpecHandle  commentHandle;   // Handle to all the comment information.
  long               uniqueFonts;     // The number of unique fonts in the picture.
  FontSpecHandle     fontHandle;      // Handle to the FontSpec information.
  Handle             fontNamesHandle; // Handle to the font names.
  long  reserved1;
  long  reserved2;
};
typedef struct PictInfo PictInfo;
typedef PictInfo *PictInfoPtr;
typedef PictInfoPtr *PictInfoHandle;

struct CommentSpec
{
  short  count; // Number of occurrences of this comment ID.
  short  ID;    // ID for the comment in the picture.
};
typedef struct CommentSpec CommentSpec;
typedef CommentSpec *CommentSpecPtr;
typedef CommentSpecPtr *CommentSpecHandle;

struct FontSpec
{
  short  pictFontID;  // ID of the font in the picture.
  short  sysFontID;   // ID of the same font in the current system file.
  long   size[4];     // Bit array of all the sizes found (1..127) (bit 0 means > 127).
  short  style;       // Combined style of all occurrances of the font.
  long   nameOffset;  // Offset into the fontNamesHdl handle for the font's name.
};
typedef struct FontSpec FontSpec;
typedef FontSpec *FontSpecPtr;
typedef FontSpecPtr *FontSpecHandle;

PicHandle  OpenCPicture(const OpenCPicParams *newHeader);
void       PicComment(short kind,short dataSize,Handle dataHandle);
void       ClosePicture(void);
void       KillPicture(PicHandle myPicture);

void       DrawPicture(PicHandle myPicture,const Rect *dstRect)
PicHandle  GetPicture(Integer picID);

OSErr  GetPictInfo(PicHandle thePictHandle,PictInfo *thePictInfo,short verb,
       short colorsRequested,short colorPickMethod,short version);
OSErr  GetPixMapInfo(PixMapHandle thePixMapHandle,PictInfo *thePictInfo,short verb,
       short colorsRequested,short colorPickMethod,short version);
OSErr  NewPictInfo(PictInfoID *thePictInfoID,short verb,short colorsRequested,
       short colorPickMethod,short version);
OSErr  RecordPictInfo(PictInfoID thePictInfoID,PicHandle thePictHandle);
OSErr  RecordPixMapInfo(PictInfoID thePictInfoID,PixMapHandle thePixMapHandle);
OSErr  RetrievePictInfo(PictInfoID thePictInfoID,PictInfo *thePictInfo,
       short colorsRequested);
OSErr  DisposPictInfo(PictInfoID thePictInfoID);

iBeamCursor  = 1
crossCursor  = 2
plusCursor   = 3
watchCursor  = 4

struct Cursor
{
  Bits16  data;
  Bits16  mask;
  Point   hotSpot;
};
typedef struct Cursor Cursor;
typedef Cursor *CursPtr;
typedef CursPtr *CursHandle;

struct CCrsr
{
  short         crsrType;     // Type of cursor.
  PixMapHandle  crsrMap;      // The cursor's pixmap.
  Handle        crsrData;     // Cursor's data.
  Handle        crsrXData;    // Expanded cursor data.
  short         crsrXValid;   // Depth of expanded data (0 if none).
  Handle        crsrXHandle;  // Future use.
  Bits16        crsr1Data;    // One-bit cursor.
  Bits16        crsrMask;     // Cursor's mask.
  Point         crsrHotSpot;  // Cursor's hotspot.
  long          crsrXTable;   // Private.
  long          crsrID;       // Private.
};
typedef struct CCrsr CCrsr;
typedef CCrsr *CCrsrPtr;
typedef CCrsrPtr *CCrsrHandle;

struct Acur 
{
  short  n;       // Number of cursors (frames).
  short  index;   // (Reserved.)
  short  frame1;  // 'CURS' resource ID for frame #1.
  short  fill1;   // (Recerved.)
  short  frame2;  // 'CURS' resource ID for frame #2.
  short  fill2;   // (Reserved.)
  short  frameN;  // 'CURS' resource ID for frame #n.
  short  fillN;   // (Reserved.)
};
typedef struct Acur acur, *acurPtr, **acurHandle;

void  InitCursor(void);
void  InitCursorCtl(acurHandle newCursors);

CursHandle  GetCursor(short cursorID);
void        SetCursor(const Cursor *crsr);

CCrsrHandle  GetCCursor(short crsrID);
void         SetCCursor(CCrsrHandle cCrsr);
void         AllocCursor(void)
void         DisposCCursor(CCrsrHandle cCrsr);
void         DisposeCCursor(CCrsrHandle cCrsr);

void    HideCursor(void);
void    ShowCursor(void);
void    ObscureCursor(void);
void    ShieldCursor(const Rect *shieldRect,Point offsetPt);
void    RotateCursor(long counter);
pascal  void SpinCursor(short increment);

kThemeStateDisabled  = 0
kThemeStateActive    = 1
kThemeStatePressed   = 2

kThemeArrowCursor                 = 0
kThemeCopyArrowCursor             = 1
kThemeAliasArrowCursor            = 2
kThemeContextualMenuArrowCursor   = 3
kThemeIBeamCursor                 = 4
kThemeCrossCursor                 = 5
kThemePlusCursor                  = 6
kThemeWatchCursor                 = 7   // Can animate
kThemeClosedHandCursor            = 8
kThemeOpenHandCursor              = 9
kThemePointingHandCursor          = 10
kThemeCountingUpHandCursor        = 11  // Can animate
kThemeCountingDownHandCursor      = 12  // Can animate
kThemeCountingUpAndDownHandCursor = 13  // Can animate
kThemeSpinningCursor              = 14  // Can animate
kThemeResizeLeftCursor            = 15
kThemeResizeRightCursor           = 16
kThemeResizeLeftRightCursor       = 17

typedef UInt32 ThemeCursor;

OSStatus  SetThemeCursor(ThemeCursor inCursor);
OSStatus  SetAnimatedThemeCursor(ThemeCursor inCursor,UInt32 inAnimationStep);

kLarge1BitMask  = FOUR_CHAR_CODE('ICN#')
kLarge4BitData  = FOUR_CHAR_CODE('icl4')
kLarge8BitData  = FOUR_CHAR_CODE('icl8')
kSmall1BitMask  = FOUR_CHAR_CODE('ics#')
kSmall4BitData  = FOUR_CHAR_CODE('ics4')
kSmall8BitData  = FOUR_CHAR_CODE('ics8')
kMini1BitMask   = FOUR_CHAR_CODE('icm#')
kMini4BitData   = FOUR_CHAR_CODE('icm4')
kMini8BitData   = FOUR_CHAR_CODE('icm8')

kAlignNone              = 0x00
kAlignVerticalCenter    = 0x01
kAlignTop               = 0x02
kAlignBottom            = 0x03
kAlignHorizontalCenter  = 0x04
kAlignAbsoluteCenter    = kAlignVerticalCenter | kAlignHorizontalCenter
kAlignCenterTop         = kAlignTop            | kAlignHorizontalCenter
kAlignCenterBottom      = kAlignBottom         | kAlignHorizontalCenter
kAlignLeft              = 0x08,
kAlignCenterLeft        = kAlignVerticalCenter | kAlignLeft
kAlignTopLeft           = kAlignTop            | kAlignLeft
kAlignBottomLeft        = kAlignBottom         | kAlignLeft
kAlignRight             = 0x0C,
kAlignCenterRight       = kAlignVerticalCenter | kAlignRight
kAlignTopRight          = kAlignTop            | kAlignRight
kAlignBottomRight       = kAlignBottom         | kAlignRight

kTransformNone              = 0x00
kTransformDisabled          = 0x01
kTransformOffline           = 0x02
kTransformOpen              = 0x03
kTransformLabel1            = 0x0100
kTransformLabel2            = 0x0200
kTransformLabel3            = 0x0300
kTransformLabel4            = 0x0400
kTransformLabel5            = 0x0500
kTransformLabel6            = 0x0600
kTransformLabel7            = 0x0700
kTransformSelected          = 0x4000
kTransformSelectedDisabled  = kTransformSelected | kTransformDisabled
kTransformSelectedOffline   = kTransformSelected | kTransformOffline
kTransformSelectedOpen      = kTransformSelected | kTransformOpen

kSelectorLarge1Bit     = 0x00000001
kSelectorLarge4Bit     = 0x00000002
kSelectorLarge8Bit     = 0x00000004
kSelectorSmall1Bit     = 0x00000100
kSelectorSmall4Bit     = 0x00000200
kSelectorSmall8Bit     = 0x00000400
kSelectorMini1Bit      = 0x00010000
kSelectorMini4Bit      = 0x00020000
kSelectorMini8Bit      = 0x00040000
kSelectorAllLargeData  = 0x000000FF
kSelectorAllSmallData  = 0x0000FF00
kSelectorAllMiniData   = 0x00FF0000
kSelectorAll1BitData   = kSelectorLarge1Bit | kSelectorSmall1Bit | kSelectorMini1Bit
kSelectorAll4BitData   = kSelectorLarge4Bit | kSelectorSmall4Bit | kSelectorMini4Bit
kSelectorAll8BitData   = kSelectorLarge8Bit | kSelectorSmall8Bit | kSelectorMini8Bit
kSelectorAllAvailableData  = (long)0xFFFFFFFF

typedef short   IconAlignmentType;
typedef short   IconTransformType;
typedef UInt32  IconSelectorValue;
typedef Handle  IconSuiteRef;
typedef Handle  IconCacheRef;

struct CIcon 
{
  PixMap  iconPMap;         // Icon's pixMap.
  BitMap  iconMask;         // Icon's mask.
  BitMap  iconBMap;         // Icon's bitMap.
  Handle  iconData;         // Icon's data.
  short   iconMaskData[1];  // Icon's mask and BitMap data.
};
typedef struct CIcon CIcon;
typedef CIcon *CIconPtr;
typedef CIconPtr *CIconHandle;

OSErr  PlotIconID(constRect *theRect,IconAlignmentType align,
       IconTransformType transform,short theResID);
void   PlotIcon(const Rect *theRect,Handle theIcon);
OSErr  PlotIconHandle(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,Handle theIcon);
void   PlotCIcon(const Rect *theRect,CIconHandle theIcon);
OSErr  PlotCIconHandle(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,CIconHandle theIcon);
OSErr  PlotSICNHandle(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,Handle theSICN);

Handle       GetIcon(short iconID); 
CIconHandle  GetCIcon(short iconID);

OSErr  DisposeCIcon(CIconHandle theIcon);

OSErr  GetIconSuite(Handle *theIconSuite,short theResID,IconSelectorValue selector);;
OSErr  NewIconSuite(Handle *theIconSuite);
OSErr  AddIconToSuite(Handle theIconData,Handle theSuite,ResType theType);

OSErr  GetIconFromSuite(Handle *theIconData,Handle theSuite,ResType theType);

OSErr  PlotIconSuite(const Rect *theRect,IconAlignmentType align,
      IconTransformType transform,Handle theIconSuite);

OSErr  ForEachIconDo(handle theSuite,IconSelectorValue selector, IconActionUPP action,
       void *yourDataPtr);

OSErr  DisposeIconSuite(Handle theIconSuite,Boolean disposeData);

OSErr  IconSuiteToRgn(RgnHandle theRgn,const Rect *iconRect,
       IconAlignmentType align,Handle theIconSuite);
OSErr  IconIDToRegion(RgnHandle theRgn,const Rect *iconRect,
       IconAlignmentType align,short iconID);

Boolean  PtInIconSuite(Point testPt,const Rect *iconRect,IconAlignmentType align,
         Handle theIconSuite);
Boolean  PtInIconID(Point testPt,const Rect *iconRect,IconAlignmentType align,
         short iconID);
Boolean  RectInIconSuite(const Rect *testRect,const Rect *iconRect,
         IconAlignmentType align,Handle theIconSuite);
Boolean  RectInIconID(const Rect *testRect,const Rect *iconRect,IconAlignmentType align,
         short iconID);

OSErr  MakeIconCache(Handle *theHandle,IconGetterProcPtr makeIcon,void *yourDataPtr);
OSErr  LoadIconCache(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,Handle theIconCache);