Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Summary of the Icon Utilities
Pascal Summary
Constants
CONST gestaltIconUtilitiesAttr = 'icon'; {Icon Utilities attributes} gestaltIconUtilitiesPresent= 0; {check this bit in the } { response parameter} {types for icon families} large1BitMask = 'ICN#'; {icon list resource for large icons} large4BitData = 'icl4'; {large 4-bit color icon resource} large8BitData = 'icl8'; {large 8-bit color icon resource} small1BitMask = 'ics#'; {icon list resource for small icons} small4BitData = 'ics4'; {small 4-bit color icon resource} small8BitData = 'ics8'; {small 8-bit color icon resource} mini1BitMask = 'icm#'; {icon list resource for mini icons} mini4BitData = 'icm4'; {4-bit color mini icon} mini8BitData = 'icm8'; {8-bit color mini icon resource} {IconAlignmentType values} atNone = $0; {no alignment} atVerticalCenter = $1; {centered vertically} atTop = $2; {top aligned} atBottom = $3; {bottom aligned} atHorizontalCenter = $4; {centered horizontally} atLeft = $8; {left aligned} atRight = $C; {right aligned} atAbsoluteCenter = (atVerticalCenter + atHorizontalCenter); atCenterTop = (atTop + atHorizontalCenter); atCenterBottom = (atBottom + atHorizontalCenter); atCenterLeft = (atVerticalCenter + atLeft); atTopLeft = (atTop + atLeft); atBottomLeft = (atBottom + atLeft); atCenterRight = (atVerticalCenter + atRight); atTopRight = (atTop + atRight); atBottomRight = (atBottom + atRight); {IconTransformType values} ttNone = $0; ttDisabled = $1; ttOffline = $2; ttOpen = $3; ttLabel1 = $0100; ttLabel2 = $0200; ttLabel3 = $0300; ttLabel4 = $0400; ttLabel5 = $0500; ttLabel6 = $0600; ttLabel7 = $0700; ttSelected = $4000; ttSelectedDisabled = (ttSelected + ttDisabled); ttSelectedOffline = (ttSelected + ttOffline); ttSelectedOpen = (ttSelected + ttOpen); {IconSelectorValue masks} svLarge1Bit = $00000001; {'ICN#' resource} svLarge4Bit = $00000002; {'icl4' resource} svLarge8Bit = $00000004; {'icl8' resource} svSmall1Bit = $00000100; {'ics#' resource} svSmall4Bit = $00000200; {'ics4' resource} svSmall8Bit = $00000400; {'ics8' resource} svMini1Bit = $00010000; {'icm#' resource} svMini4Bit = $00020000; {'icm4' resource} svMini8Bit = $00040000; {'icm8' resource} svAllLargeData = $000000FF; {'ICN#', 'icl4', and 'icl8' } { resources} svAllSmallData = $0000FF00; {'ics#', 'ics4', and 'ics8' } { resources} svAllMiniData = $00FF0000; {'icm#', 'icm4', and 'icm8' } { resources} svAll1BitData = (svLarge1Bit + svSmall1Bit + svMini1Bit); svAll4BitData = (svLarge4Bit + svSmall4Bit + svMini4Bit); svAll8BitData = (svLarge8Bit + svSmall8Bit + svMini8Bit); svAllAvailableData = $FFFFFFFF; {all resources of given ID}Data Types
TYPE CIcon = RECORD iconPMap: PixMap; {the icon's pixel map} iconMask: BitMap; {the icon's mask} iconBMap: BitMap; {the icon's bitmap} iconData: Handle; {handle to the icon's data} iconMaskData: {the data for the icon's mask} ARRAY[0..0] OF Integer; END; CIconPtr = ^CIcon; {pointer to color icon record} CIconHandle = ^CIconPtr; {handle to color icon record} IconSelectorValue = LongInt; {icon selector type} IconAlignmentType = Integer; {icon alignment type} IconTransformType = Integer; {icon transform type} IconAction = ProcPtr; {pointer to action function} IconGetter = ProcPtr; {pointer to icon getter function}Icon Utilities Routines
Drawing Icons From Resources
FUNCTION PlotIconID (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theResID: Integer): OSErr; FUNCTION PlotIconMethod (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theMethod: IconGetter; yourDataPtr: UNIV Ptr): OSErr; PROCEDURE PlotIcon (theRect: Rect; theIcon: Handle); FUNCTION PlotIconHandle (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theIcon: Handle): OSErr; PROCEDURE PlotCIcon (theRect: Rect; theIcon: CIconHandle); FUNCTION PlotCIconHandle (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theCIcon: CIconHandle): OSErr; FUNCTION PlotSICNHandle (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theSICN: Handle): OSErr;Getting Icons From Resources That Don't Belong to an Icon Family
FUNCTION GetIcon (iconID: Integer): Handle; FUNCTION GetCIcon (iconID: Integer): CIconHandle;Disposing of Icons
PROCEDURE DisposeCIcon (theIcon: CIconHandle);Creating an Icon Suite
FUNCTION GetIconSuite (VAR theIconSuite: Handle; theResID: Integer; selector: IconSelectorValue): OSErr; FUNCTION NewIconSuite (VAR theIconSuite: Handle): OSErr; FUNCTION AddIconToSuite (theIconData: Handle; theSuite: Handle; theType: ResType): OSErr;Getting Icons From an Icon Suite
FUNCTION GetIconFromSuite (VAR theIconData: Handle; theSuite: Handle; theType: ResType): OSErr;Drawing Icons From an Icon Suite
FUNCTION PlotIconSuite (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theIconSuite: Handle): OSErr;Performing Operations on Icons in an Icon Suite
FUNCTION ForEachIconDo (theSuite: Handle; selector: IconSelectorValue; action: IconAction; yourDataPtr: Ptr): OSErr;Getting and Setting the Label for an Icon Suite
FUNCTION GetSuiteLabel (theSuite: Handle): Integer; FUNCTION SetSuiteLabel (theSuite: Handle; theLabel: Integer): OSErr;Getting Label Information
FUNCTION GetLabel (labelNumber: Integer; VAR labelColor: RGBColor; VAR labelString: Str255): OSErr;Disposing of Icon Suites
FUNCTION DisposeIconSuite (theIconSuite: Handle; disposeData: Boolean): OSErr;Converting an Icon Mask to a Region
FUNCTION IconSuiteToRgn (theRgn: RgnHandle; iconRect: Rect; align: IconAlignmentType; theIconSuite: Handle): OSErr; FUNCTION IconIDToRgn (theRgn: RgnHandle; iconRect: Rect; align: IconAlignmentType; iconID: Integer): OSErr; FUNCTION IconMethodToRgn (theRgn: RgnHandle; iconRect: Rect; align: IconAlignmentType; theMethod: IconGetter; yourDataPtr: Ptr): OSErr;Determining Whether a Point or Rectangle Is Within an Icon
FUNCTION PtInIconSuite (testPt: Point; iconRect: Rect; align: IconAlignmentType; theIconSuite: Handle): Boolean; FUNCTION PtInIconID (testPt: Point; iconRect: Rect; align: IconAlignmentType; iconID: Integer): Boolean; FUNCTION PtInIconMethod (testPt: Point; iconRect: Rect; align: IconAlignmentType; theMethod: IconGetter; yourDataPtr: Ptr): Boolean; FUNCTION RectInIconSuite (testRect: Rect; iconRect: Rect; align: IconAlignmentType; theIconSuite: Handle): Boolean; FUNCTION RectInIconID (testRect: Rect; iconRect: Rect; align: IconAlignmentType; iconID: Integer): Boolean; FUNCTION RectInIconMethod (testRect: Rect; iconRect: Rect; align: IconAlignmentType; theMethod: IconGetter; yourDataPtr: Ptr): Boolean;Working With Icon Caches
FUNCTION MakeIconCache (VAR theHandle: Handle; makeIcon: IconGetter; yourDataPtr: UNIV Ptr): OSErr; FUNCTION LoadIconCache (theRect: Rect; align: IconAlignmentType; transform: IconTransformType; theIconCache: Handle): OSErr; FUNCTION GetIconCacheData (theCache: Handle; VAR theData: Ptr): OSErr; FUNCTION SetIconCacheData (theCache: Handle; theData: Ptr): OSErr; FUNCTION GetIconCacheProc (theCache: Handle; VAR theProc: IconGetter): OSErr; FUNCTION SetIconCacheProc (theCache: Handle; theProc: IconGetter): OSErr;Application-Defined Routines
Icon Action Functions
FUNCTION MyIconAction (theType: ResType; VAR theIcon: Handle; yourDataPtr: Ptr): OSErr;Icon Getter Functions
FUNCTION MyIconGetter (theType: ResType; yourDataPtr: Ptr): Handle;C Summary
Constants
enum { #define gestaltIconUtilitiesAttr 'icon' /*Icon Utilities attributes*/ gestaltIconUtilitiesPresent = 0 /*check this bit in the */ /* response parameter*/ }; /*types for icon families*/ #define large1BitMask 'ICN#' /*icon list resource for large icons*/ #define large4BitData 'icl4' /*large 4-bit color icon resource*/ #define large8BitData 'icl8' /*large 8-bit color icon resource*/ #define small1BitMask 'ics#' /*icon list resource for small icons*/ #define small4BitData 'ics4' /*small 4-bit color icon resource*/ #define small8BitData 'ics8' /*small 8-bit color icon resource*/ #define mini1BitMask 'icm#' /*icon list resource for mini icons*/ #define mini4BitData 'icm4' /*mini 4-bit color icon resource*/ #define mini8BitData 'icm8' /*mini 4-bit color icon resource*/ enum { /*IconAlignmentType values*/ atNone = 0x0, /*no alignment*/ atVerticalCenter = 0x1, /*centered vertically*/ atTop = 0x2, /*top aligned*/ atBottom = 0x3, /*bottom aligned*/ atHorizontalCenter = 0x4, /*centered horizontally*/ atAbsoluteCenter = (atVerticalCenter | atHorizontalCenter), atCenterTop = (atTop | atHorizontalCenter), atCenterBottom = (atBottom | atHorizontalCenter), atLeft = 0x8, /*left aligned*/ atCenterLeft = (atVerticalCenter | atLeft), atTopLeft = (atTop | atLeft), atBottomLeft = (atBottom | atLeft), atRight = 0xC, /*right aligned*/ atCenterRight = (atVerticalCenter | atRight), atTopRight = (atTop | atRight), atBottomRight = (atBottom | atRight), }; enum { /*IconTransformType values*/ ttNone = 0x0, ttDisabled = 0x1, ttOffline = 0x2, ttOpen = 0x3, ttLabel1 = 0x0100, ttLabel2 = 0x0200, ttLabel3 = 0x0300, ttLabel4 = 0x0400, ttLabel5 = 0x0500, ttLabel6 = 0x0600, ttLabel7 = 0x0700, ttSelected = 0x4000, ttSelectedDisabled = (ttSelected | ttDisabled), ttSelectedOffline = (ttSelected | ttOffline), ttSelectedOpen = (ttSelected | ttOpen), }; enum { /*IconSelectorValue masks*/ svLarge1Bit = 0x00000001, /*'ICN#' resource*/ svLarge4Bit = 0x00000002, /*'icl4' resource*/ svLarge8Bit = 0x00000004, /*'icl8' resource*/ svSmall1Bit = 0x00000100, /*'ics#' resource*/ svSmall4Bit = 0x00000200, /*'ics4' resource*/ svSmall8Bit = 0x00000400, /*'ics8' resource*/ svMini1Bit = 0x00010000, /*'icm#' resource*/ svMini4Bit = 0x00020000, /*'icm4' resource*/ svMini8Bit = 0x00040000, /*'icm8' resource*/ svAllLargeData = 0x000000FF, /*'ICN#', 'icl4', and 'icl8' */ /* resources*/ svAllSmallData = 0x0000FF00, /*'ics#', 'ics4', and 'ics8' */ /* resources*/ svAllMiniData = 0x00FF0000, /*'icm#', 'icm4', and 'icm8' */ /* resources*/ svAll1BitData = (svLarge1Bit | svSmall1Bit | svMini1Bit), svAll4BitData = (svLarge4Bit | svSmall4Bit | svMini4Bit), svAll8BitData = (svLarge8Bit | svSmall8Bit | svMini8Bit), svAllAvailableData = (long)0xFFFFFFFF /*all resources of given ID*/ };Data Types
struct CIcon { PixMap iconPMap; /*the icon's pixel map*/ BitMap iconMask; /*the icon's mask*/ BitMap iconBMap; /*the icon's bitmap*/ Handle iconData; /*handle to the icon's data*/ short iconMaskData: /*the data for the icon's mask*/ }; typedef struct CIcon CIcon; typedef Cicon *CIconPtr, **CIconHandle; /*ptr, handle to color icon record*/ typedef unsigned long IconSelectorValue;/*icon selector type*/ typedef short IconAlignmentType; /*icon alignment type*/ typedef short IconTransformType; /*icon transform type*/ /*pointer to action function*/ typedef pascal OSErr (*IconActionProcPtr)(ResType theType, Handle *theIcon, void *yourDataPtr); typedef IconActionProcPtr IconAction; /*pointer to icon getter function*/ typedef pascal Handle (*IconGetterProcPtr)(ResType theType, void *yourDataPtr); typedef IconGetterProcPtr IconGetter;Icon Utilities Routines
Drawing Icons From Resources
pascal OSErr PlotIconID (const Rect *theRect, IconAlignmentType align, IconTransformType transform, short theResID); pascal OSErr PlotIconMethod (const Rect *theRect, IconAlignmentType align, IconTransformType transform, IconGetterProcPtr theMethod, void *yourDataPtr); pascal void PlotIcon (const Rect *theRect, Handle theIcon); pascal OSErr PlotIconHandle (const Rect *theRect, IconAlignmentType align, IconTransformType transform, Handle theIcon); pascal OSErr PlotCIcon (const Rect *theRect, CIconHandle theIcon); pascal OSErr PlotCIconHandle (const Rect *theRect, IconAlignmentType align, IconTransformType transform, CIconHandle theCIcon); pascal OSErr PlotSICNHandle (const Rect *theRect, IconAlignmentType align, IconTransformType transform, Handle theSICN);Getting Icons From Resources That Don't Belong to an Icon Family
pascal Handle GetIcon (short iconID); pascal CIconHandle GetCIcon (short iconID);Disposing of Icons
pascal OSErr DisposeCIcon (CIconHandle theIcon);Creating an Icon Suite
pascal OSErr GetIconSuite (Handle *theIconSuite, short theResID, IconSelectorValue selector); pascal OSErr NewIconSuite (Handle *theIconSuite); pascal OSErr AddIconToSuite (Handle theIconData, Handle theSuite, ResType theType);Getting Icons From an Icon Suite
pascal OSErr GetIconFromSuite (Handle *theIconData, Handle theSuite, ResType theType);Drawing Icons From an Icon Suite
pascal OSErr PlotIconSuite (const Rect *theRect, IconAlignmentType align, IconTransformType transform, Handle theIconSuite);Performing Operations on Icons in an Icon Suite
pascal OSErr ForEachIconDo (Handle theSuite, IconSelectorValue selector, IconActionProcPtr action, void *yourDataPtr);Getting and Setting the Label for an Icon Suite
pascal short GetSuiteLabel (Handle theSuite); pascal OSErr SetSuiteLabel (Handle theSuite, short theLabel);Getting Label Information
pascal OSErr GetLabel (short labelNumber, RGBColor *labelColor, Str255 labelString);Disposing of Icon Suites
pascal OSErr DisposeIconSuite (Handle theIconSuite, Boolean disposeData);Converting an Icon Mask to a Region
pascal OSErr IconSuiteToRgn (RgnHandle theRgn, const Rect *iconRect, IconAlignmentType align, Handle theIconSuite); pascal OSErr IconIDToRgn (RgnHandle theRgn, const Rect *iconRect, IconAlignmentType align, short iconID); pascal OSErr IconMethodToRgn (RgnHandle theRgn, const Rect *iconRect, IconAlignmentType align, IconGetterProcPtr theMethod, void *yourDataPtr);Determining Whether a Point or Rectangle Is Within an Icon
pascal Boolean PtInIconSuite (Point testPt, const Rect *iconRect, IconAlignmentType align, Handle theIconSuite); pascal Boolean PtInIconID (Point testPt, const Rect *iconRect, IconAlignmentType align, short iconID); pascal Boolean PtInIconMethod (Point testPt, const Rect *iconRect, IconAlignmentType align, IconGetterProcPtr theMethod, void *yourDataPtr); pascal Boolean RectInIconSuite (const Rect *testRect, const Rect *iconRect, IconAlignmentType align, Handle theIconSuite); pascal Boolean RectInIconID (const Rect *testRect, const Rect *iconRect, IconAlignmentType align, short iconID); pascal Boolean RectInIconMethod (const Rect *testRect, const Rect *iconRect, IconAlignmentType align, IconGetterProcPtr theMethod, void *yourDataPtr);Working With Icon Caches
pascal OSErr MakeIconCache (Handle *theHandle, IconGetterProcPtr makeIcon, void *yourDataPtr); pascal OSErr LoadIconCache (const Rect *theRect, IconAlignmentType align, IconTransformType transform, Handle theIconCache); pascal OSErr GetIconCacheData (Handle theCache, void **theData); pascal OSErr SetIconCacheData (Handle theCache, void *theData); pascal OSErr GetIconCacheProc (Handle theCache, IconGetter *theProc); pascal OSErr SetIconCacheProc (Handle theCache, IconGetter theProc);Application-Defined Routines
Icon Action Functions
pascal OSErr MyIconAction (ResType theType, Handle *theIcon, void *yourDataPtr);Icon Getter Functions
pascal Handle MyIconGetter (ResType theType, void *yourDataPtr);Assembly-Language Summary
Data Structure
Color Icon Data Structure
0 iconPMap 60 bytes icon's pixel map 50 iconMask 14 bytes icon's mask 64 iconBMap 14 bytes icon's bitmap 78 iconData 4 bytes handle to icon's data 82 iconMaskData variable data for icon's mask Trap Macros
Trap Macros Requiring Routine Selectors
_IconDispatch
Selector Routine $0702 NewIconSuite $1702 GetSuiteLabel $0203 DisposeIconSuite $1603 SetSuiteLabel $1904 GetIconCacheData $1A04 SetIconCacheData $1B04 GetIconCacheProc $1C04 SetIconCacheProc $0005 PlotIconID $0105 GetIconSuite $0B05 GetLabel $0306 PlotIconSuite $0406 MakeIconCache $0606 LoadIconCache $0806 AddIconToSuite $0906 GetIconFromSuite $0D06 PtInIconID $1006 RectInIconID $1306 IconIDToRgn $1D06 PlotIconHandle $1E06 PlotSICNHandle $1F06 PlotCIconHandle $0E07 PtInIconSuite $1107 RectInIconSuite $1407 IconSuiteToRgn $0A08 ForEachIconDo $0508 PlotIconMethod $0F09 PtInIconMethod $1209 RectInIconMethod $1509 IconMethodToRgn Result Codes
noErr 0 No error paramErr -50 Error in parameter list memFullErr -108 Not enough memory in heap zone memWZErr -111 Attempt to operate on a free block resNotFound -192 Resource not found noMaskFoundErr -1000 Cannot find or create mask for the icon family