Next Page >

Hide TOC

Icon Services and Utilities Reference

Framework	Carbon/Carbon.h
Declared in	Icons.h IconsCore.h

Overview

The Icon Utilities allow your application (and system software) to manipulate and draw icons of any standard resource type in windows and if necessary in menus or dialog boxes. You need to use these routines only if you wish to draw icons in your application’s windows or to draw icons whose resource types are not recognized by the Menu Manager and Dialog Manager in menus and dialog boxes.

To display an icon most effectively at a variety of sizes and bit depths, you should provide an icon family. You can then draw the appropriate member of the family for a given size and bit depth either by passing the family’s resource ID to an Icon Utilities routine or by reading the family’s icon resources into memory as an icon suite and passing the suite’s handle to Icon Utilities routines.

Icon Services provides icon data to multiple Mac OS clients, including the Finder, extensions and applications. Using Icon Services to obtain icon data means you can provide efficient icon caching and release memory when you don't need icon data any longer. Icon Services provides the appropriate icon for any file object (file, folder, or volume), as well as other commonly used icons such as caution, note, or help icons in alert boxes, for example. The icons provided by Icon Services support a much larger palette of colors: up to 24 bits per pixel and an eight-bit mask. Icons are Appearance-compliant and appropriate to the active theme.

Functions by Task

Converting an Icon Mask to a Region

Creating an Icon Suite

Determining Whether a Point Is Within an Icon

Determining Whether a Rectangle Intersects an Icon

Disposing of Icon Suites

Disposing of Icons

Drawing Icons From an Icon Suite

Drawing Icons From Resources

Enabling and Disabling Custom Icons

Flushing IconRef Data

Getting and Setting the Label for an Icon Suite

Getting Label Information

Getting Icons From an Icon Suite

Getting Icons From Resources That Don’t Belong to an Icon Family

IconRef Reference Counting

Modifying IconRef Data

Obtaining Icon Data

Obtaining IconRef Values

Performing Operations on Icons in an Icon Suite

Reading, Copying, and Converting Icon Data

Registering and Unregistering IconRef Values

Using IconRef Data

Working With Icon Caches

Creating and Managing Universal Procedure Pointers

Functions

AcquireIconRef

Increments the reference count for an IconRef.

OSErr AcquireIconRef (
   IconRef theIconRef
);

Parameters

theIconRef: An IconRef whose reference count you wish to increment.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

CompositeIconRef

Superimposes one IconRef onto another.

OSErr CompositeIconRef (
   IconRef backgroundIconRef,
   IconRef foregroundIconRef,
   IconRef *compositeIconRef
);

Parameters

backgroundIconRef: A value to use as the background for the composite IconRef.
foregroundIconRef: A value to use as the foregound for the composite IconRef.
compositeIconRef: On completion, this points to an IconRef that is a composite of the specified background and foreground IconRefs.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

This function provides an alternative to badging when you need to indicate a change of state.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

DisposeIconActionUPP

Disposes of the universal procedure pointer (UPP) to your icon action callback function.

void DisposeIconActionUPP (
   IconActionUPP userUPP
);

Parameters

userUPP: The UPP to dispose of.

Discussion

See the IconActionProcPtr callback for more information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

DisposeIconGetterUPP

Disposes of the universal procedure pointer (UPP) to your icon getter callback function.

void DisposeIconGetterUPP (
   IconGetterUPP userUPP
);

Parameters

userUPP: The UPP to dispose of.

Discussion

See the IconGetterProcPtr callback for more information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

GetCustomIconsEnabled

Determines whether custom icons are enabled or disabled on a specified volume.

OSErr GetCustomIconsEnabled (
   SInt16 vRefNum,
   Boolean *customIconsEnabled
);

Parameters

vRefNum: The volume whose status you are querying.
customIconsEnabled: On return, customIconsEnabled points to the value true if custom icons are enabled on the volume specified or false if custom icons are disabled on the volume specified.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

GetIconFamilyData

Obtains a copy of the raw icon data for an individual element in an icon family.

OSErr GetIconFamilyData (
   IconFamilyHandle iconFamily,
   OSType iconType,
   Handle h
);

Parameters

iconFamily: A handle to an iconFamily data structure to use as a source for icon data.
iconType: The format of the icon data you want to obtain.You may specify one of the icon types (as defined in IconStorage.h in the CoreServices/OSServices framework) or 'PICT' in this parameter. For example, you can pass kThumbnail32BitData ('it32'), to obtain 65,536 bytes of raw bitmap data.
h: A handle to the icon data being returned. Icon Services resizes this handle as needed. If no data is available for the specified icon family, Icon Services sets the handle to 0.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

GetIconRef

Provides an IconRef object for an icon in the desktop database or for a registered icon.

OSErr GetIconRef (
   SInt16 vRefNum,
   OSType creator,
   OSType iconType,
   IconRef *theIconRef
);

Parameters

vRefNum: The volume where Icon Services should start to search for the desired icon. Pass the kOnSystemDisk constant if you are not sure which value to specify in this parameter.
creator: The creator code of the desired icon.
iconType: The type code of the desired icon.
theIconRef: On return, a pointer to an IconRef object. You are responsible for releasing the object by calling ReleaseIconRef.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

Icon Services defines constants for commonly-used system icons. You can pass one of these constants in the iconType parameter if you specify kSystemIconsCreator in the creator parameter. See “Folder Icon Constants” for a list of these constants.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

GetIconRefFromComponent

Provides an IconRef object based on a specified component.

OSStatus GetIconRefFromComponent (
   Component inComponent,
   IconRef *outIconRef
);

Parameters

inComponent: The component whose icon data you want to obtain.
outIconRef: On return, a pointer to an IconRef object based on the componentIconFamily field of the specified component's 'thng' resource. You are responsible for releasing the object by calling ReleaseIconRef.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

This function obtains an IconRef object based on the resource ID of an icon family. A component can provide an icon family in addition to the icon provided in the componentIcon field. Note that members of this icon family are not used by the Finder; you supply an icon family only so that other components or applications can display your component's icon in their user interfaces if needed.

Availability

Available in Mac OS X v10.5 and later.

Declared In

IconsCore.h

GetIconRefFromFileInfo

Provides an IconRef object for a file with minimal file I/O.

OSStatus GetIconRefFromFileInfo (
   const FSRef *inRef,
   UniCharCount inFileNameLength,
   const UniChar *inFileName,
   FSCatalogInfoBitmap inWhichInfo,
   const FSCatalogInfo *inCatalogInfo,
   IconServicesUsageFlags inUsageFlags,
   IconRef *outIconRef,
   SInt16 *outLabel
);

Parameters

inRef: A pointer to an FSRef for the target file.
inFileNameLength: The length of the name of the target file.
inFileName: A pointer to the name of the target file.
inWhichInfo: The mask of the file information contained in the inCatalogInfo parameter.
inCatalogInfo: A pointer to the catalog information.
inUsageFlags: The usage flags for this call; use kIconServicesNormalUsageFlag.
outIconRef: On return, a pointer to an IconRef object. You are responsible for releasing the object by calling ReleaseIconRef.
outLabel: On return, a pointer to the output label for the icon/file.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

To minimize file operations, FSGetCatalogInfo should be called prior to calling this function. The information in the FSCatalogInfo structure should correspond to that specified by kIconServicesCatalogInfoMask. The name should be fetched and passed in. If either the name or the correct catalog information is not passed in, this function will do file operations for this information instead.

Availability

Available in Mac OS X v10.1 and later.

Declared In

IconsCore.h

GetIconRefFromFolder

Provides an IconRef object for a folder with no custom icon.

OSErr GetIconRefFromFolder (
   SInt16 vRefNum,
   SInt32 parentFolderID,
   SInt32 folderID,
   SInt8 attributes,
   SInt8 accessPrivileges,
   IconRef *theIconRef
);

Parameters

vRefNum: The volume where the folder is located.
parentFolderID: The ID of the desired folder’s parent folder.
folderID: The ID of the desired folder.
attributes: The attributes of the desired folder. You can obtain this data from the CInfoPBRec.dirInfo.ioFlAttrib field of the folder’s catalog information record.
accessPrivileges: The access privileges of the specified folder. You can obtain this data from the CInfoPBRec.dirInfo.ioACUser field of the folder’s catalog information record.
theIconRef: On return, a pointer to an IconRef object. You are responsible for releasing the object by calling ReleaseIconRef.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

If you do not have the catalog information for a folder, use the function GetIconRefFromFileInfo.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

GetIconRefFromIconFamilyPtr

Provides an IconRef object from a specified icon family.

OSStatus GetIconRefFromIconFamilyPtr (
   const IconFamilyResource *inIconFamilyPtr,
   Size inSize,
   IconRef *outIconRef
);

Parameters

inIconFamilyPtr: A pointer to an icon family. See IconStorage.h for more information.
inSize: The size of the resource buffer containing the icon family.
outIconRef: On return, a pointer to an IconRef object that matches the specified inputs. You are responsible for releasing the object by calling ReleaseIconRef.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

Typically, you do not need to use this function.

Availability

Available in Mac OS X v10.3 and later.

Declared In

IconsCore.h

GetIconRefFromTypeInfo

Provides an IconRef object with the specified type information.

OSErr GetIconRefFromTypeInfo (
   OSType inCreator,
   OSType inType,
   CFStringRef inExtension,
   CFStringRef inMIMEType,
   IconServicesUsageFlags inUsageFlags,
   IconRef *outIconRef
);

Parameters

inCreator: The creator code of the desired IconRef. You may pass 0 if the creator code is unknown.
inType: The type code of the desired IconRef. You may pass 0 if the type code is unknown.
inExtension: The file name extension of the desired IconRef. You may pass NULL if the extension is unknown.
inMIMEType: The MIME type of the desired IconRef. You may pass NULL if the MIME type is unknown.
inUsageFlags: The usage flags; use kIconServicesNormalUsageFlag.
outIconRef: On return, a pointer to an IconRef object that most closely matches the specified inputs. You are responsible for releasing the object by calling ReleaseIconRef.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

This function serves as a more versatile version of GetIconRef. If you specify creator and type codes and do not specify the extension and MIME type, calling this function is equivalent to calling GetIconRef (kOnSystemDisk, inCreator, inType). If none of the input parameters is specified or if no match is found, this function returns the generic document icon.

Availability

Available in Mac OS X v10.3 and later.

Declared In

IconsCore.h

GetIconRefOwners

Provides the current reference count for an IconRef.

OSErr GetIconRefOwners (
   IconRef theIconRef,
   UInt16 *owners
);

Parameters

theIconRef: An IconRef whose reference count you wish to obtain.
owners: On return, a pointer to the value which represents the current reference count.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

When an IconRef’s reference count reaches 0, all memory allocated for the IconRef is marked as disposable. Any subsequent attempt to use the IconRef returns a result code of -2580 (invalidIconRefErr).

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

GetIconRefVariant

Specifies a transformation for a given IconRef.

IconRef GetIconRefVariant (
   IconRef inIconRef,
   OSType inVariant,
   IconTransformType *outTransform
);

Parameters

inIconRef

A value to be tested.

inVariant

A four-character value. You specify a variant by passing one of the following constants:

kTileIconVariant specifies a tiled icon.

kRolloverIconVariant specifies a rollover icon.

kDropIconVariant specifies a drop target icon.

kOpenIconVariant specifies an open icon.

kOpenDropIconVariant specifies a open drop target icon.

outTransform

On completion, this points to a transformation type that you pass to the function PlotIconRef for purposes of hit-testing.

Return Value

An IconRef value that you pass to the function PlotIconRef for purposes of hit-testing.

Discussion

Icon variants give you a simple way to indicate a temporary change of state by changing an icon’s appearance. For example, if you specify the kDropIconVariant value when the user drags over a valid drop target, the GetIconVariant function provides the appropriate data for you to plot the variant with the function PlotIconRef.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

IconRefContainsCGPoint

Returns a Boolean value indicating whether an icon contains a specified point.

Boolean IconRefContainsCGPoint (
   const CGPoint *testPt,
   const CGRect *iconRect,
   IconAlignmentType align,
   IconServicesUsageFlags iconServicesUsageFlags,
   IconRef theIconRef
);

Parameters

testPt: A pointer to the point to be tested. The point should be specified in the coordinate system of the rectangle specified in the iconRect parameter.
iconRect: A pointer to the rectangle in which the icon appears. The rectangle you specify should be the same rectangle that you last used to draw the icon.
align: Specifies how the icon is aligned within the rectangle specified in the iconRect parameter. The alignment you specify should be the same alignment that you last used to draw the icon. See “Icon Alignment Constants” for a description of the values you can use in this parameter.
iconServicesUsageFlags: Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.
theIconRef: The icon to test.

Return Value

TRUE if the point is in the icon and FALSE if it is not.

Discussion

This function uses the size of the rectangle you specify to determine the optimal icon mask to represent the icon. The function uses the alignment information you specify to adjust the position of the mask inside its bounding rectangle, and then determines whether the specified point is within the mask.

Availability

Available in Mac OS X v10.5 and later.

Declared In

Icons.h

IconRefIntersectsCGRect

Returns a Boolean value indicating whether an icon intersects a specified rectangle.

Boolean IconRefIntersectsCGRect (
   const CGRect *testRect,
   const CGRect *iconRect,
   IconAlignmentType align,
   IconServicesUsageFlags iconServicesUsageFlags,
   IconRef theIconRef
);

Parameters

testRect: A pointer to the rectangle to be tested. The rectangle should be specified in the coordinate system of the rectangle specified in the iconRect parameter.
iconRect: A pointer to the rectangle in which the icon appears. The rectangle you specify should be the same rectangle that you last used to draw the icon.
align: Specifies how the icon is aligned within the rectangle specified by the iconRect parameter. The alignment you specify should be the same alignment that you last used to draw the icon. See “Icon Alignment Constants” for a description of the values you can use in this parameter.
iconServicesUsageFlags: Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.
theIconRef: The icon to test.

Return Value

TRUE if the point is in the icon and FALSE if it is not.

Discussion

This function uses the size of the rectangle you specify in the iconRect parameter to determine the optimal icon mask to represent the icon. The function uses the alignment information you specify to adjust the position of the mask inside its bounding rectangle, and then determines whether the rectangle you specify in the testRect parameter intersects the mask.

Availability

Available in Mac OS X v10.5 and later.

Declared In

Icons.h

IconRefToHIShape

Converts an icon into an HIShape object.

HIShapeRef IconRefToHIShape (
   const CGRect *iconRect,
   IconAlignmentType align,
   IconServicesUsageFlags iconServicesUsageFlags,
   IconRef theIconRef
);

Parameters

iconRect: A pointer to the rectangle defining the area that Icon Services uses as the bounding box of the shape.
align: A value which determines how Icon Services aligns the shape within the rectangle. For a description of possible values, see “Icon Alignment Constants.”
iconServicesUsageFlags: Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.
theIconRef: The icon to be converted.

Return Value

An HIShape object, or NULL if the icon could not be converted.

Discussion

Availability

Available in Mac OS X v10.5 and later.

Declared In

Icons.h

IconRefToIconFamily

Provides icon family data for a given IconRef.

OSErr IconRefToIconFamily (
   IconRef theIconRef,
   IconSelectorValue whichIcons,
   IconFamilyHandle *iconFamily
);

Parameters

theIconRef: An IconRef to use as a source for icon data.
whichIcons: The depths and sizes of icons in the iconFamily data structure. For a description of the possible values, see “Icon Selector Constants.”
iconFamily: On return, a pointer to a handle to the data structure which contains icon data as specified in the IconRef and whichIcons parameters. Icon Services returns NULL if no appropriate icon data is found. For more information on the IconFamily data structure, see 'icns'.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

InvokeIconActionUPP

Calls your icon action callback function.

OSErr InvokeIconActionUPP (
   ResType theType,
   Handle *theIcon,
   void *yourDataPtr,
   IconActionUPP userUPP
);

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

You should not need to use the function InvokeIconActionUPP, as the system calls your icon action callback function for you.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

InvokeIconGetterUPP

Calls your icon getter callback function.

Handle InvokeIconGetterUPP (
   ResType theType,
   void *yourDataPtr,
   IconGetterUPP userUPP
);

Discussion

You should not need to use the function InvokeIconGetterUPP, as the system calls your icon getter callback function for you.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

IsDataAvailableInIconRef

Indicates whether an IconRef has the specified data.

Boolean IsDataAvailableInIconRef (
   OSType inIconKind,
   IconRef inIconRef
);

Parameters

inIconKind: The icon data kind. See IconStorage.h for more information.
inIconRef: The icon reference whose data you want to check.

Return Value

True if the icon reference contains the indicated data, False otherwise.

Discussion

This function can be used to determine the optimal icon size if you plan to cache a bitmap image of the icon.

Availability

Available in Mac OS X v10.3 and later.

Declared In

IconsCore.h

IsIconRefComposite

Reports whether a specified IconRef has been composited.

OSErr IsIconRefComposite (
   IconRef compositeIconRef,
   IconRef *backgroundIconRef,
   IconRef *foregroundIconRef
);

Parameters

compositeIconRef: An IconRef that you wish to test to determine whether it has been composited.
backgroundIconRef: On return, this points to the IconRef value that forms the background of the IconRef specified in the compositeIconRef parameter. If the IconRef specified in the compositeIconRef parameter is not a composite, the return value is 0.
foregroundIconRef: On return, this points to the IconRef value that forms the foreground of the IconRef specified in the compositeIconRef parameter. If the IconRef specified in the compositeIconRef parameter is not a composite, the return value is 0.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

The function CompositeIconRef allows the creation of a composite IconRef from a given background IconRef and a given foreground IconRef. The IsIconRefComposite function checks a specified IconRef to determine whether it is a composite and, if so, provides the background and foreground IconRef values.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

IsIconRefMaskEmpty

Reports whether a specified mask is empty.

Boolean IsIconRefMaskEmpty (
   IconRef iconRef
);

Parameters

iconRef: An IconRef whose mask you wish to test.

Return Value

true if the mask associated with the given IconRef is empty, false otherwise.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

IsValidIconRef

Reports whether a specified IconRef is valid.

Boolean IsValidIconRef (
   IconRef theIconRef
);

Parameters

theIconRef: An IconRef.

Return Value

true if the specified IconRef is valid, false otherwise.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

NewIconActionUPP

Creates a new universal procedure pointer (UPP) to an icon action callback function.

IconActionUPP NewIconActionUPP (
   IconActionProcPtr userRoutine
);

Parameters

userRoutine: A pointer to your icon action function.

Return Value

A UPP to the icon action function.

Discussion

See the IconActionProcPtr callback for more information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

NewIconGetterUPP

Creates a new universal procedure pointer (UPP) to an icon getter callback function.

IconGetterUPP NewIconGetterUPP (
   IconGetterProcPtr userRoutine
);

Parameters

userRoutine: A pointer to your icon getter function.

Return Value

A UPP to the icon getter function.

Discussion

See the IconGetterProcPtr callback for more information.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

OverrideIconRef

Replaces the bitmaps of one IconRef with those of another IconRef.

OSErr OverrideIconRef (
   IconRef oldIconRef,
   IconRef newIconRef
);

Parameters

oldIconRef: A pointer to a value of type IconRef whose bitmaps are to be replaced.
newIconRef: A pointer to a value of typeIconRef containing the replacement bitmaps.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

PlotIconRefInContext

Plots an IconRef using Quartz.

OSStatus PlotIconRefInContext (
   CGContextRef inContext,
   const CGRect *inRect,
   IconAlignmentType inAlign,
   IconTransformType inTransform,
   const RGBColor *inLabelColor,
   PlotIconRefFlags inFlags,
   IconRef inIconRef
);

Parameters

inContext: The graphics context to use.
inRect: A pointer to the rectangle to plot the icon in.
inAlign: The icon alignment. See “Icon Alignment Constants.”
inTransform: The icon transform. See “Icon Transformation Constants.”
inLabelColor: A pointer to the icon label color.
inFlags: The drawing flags to use; this is usually kPlotIconRefNormalFlags.
inIconRef: The IconRef to plot.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.1 and later.

Declared In

Icons.h

ReadIconFromFSRef

Reads an icon ('icns') file into memory.

OSStatus ReadIconFromFSRef (
   const FSRef *ref,
   IconFamilyHandle *iconFamily
);

Parameters

ref: A pointer to the FSRef for the icon file.
iconFamily: A pointer to the handle for the icon family.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.1 and later.

Declared In

IconsCore.h

RegisterIconRefFromFSRef

Registers an IconRef from a .icns file and associates it with a creator and type pair.

OSStatus RegisterIconRefFromFSRef (
   OSType creator,
   OSType iconType,
   const FSRef *iconFile,
   IconRef *theIconRef
);

Parameters

creator: The creator code for the .icns file.
iconType: The type code for the .icns file.
iconFile: A pointer to the FSRef of the .icns file.
theIconRef: A pointer to an IconRef. On return, this contains the registered IconRef.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.1 and later.

Declared In

IconsCore.h

RegisterIconRefFromIconFamily

Adds an iconFamily-derived IconRef to the Icon Services registry.

OSErr RegisterIconRefFromIconFamily (
   OSType creator,
   OSType iconType,
   IconFamilyHandle iconFamily,
   IconRef *theIconRef
);

Parameters

creator: The creator code of the desired icon. You can use your application’s creator code, for example. Lower-case creator codes are reserved for the System.
iconType: The type code of the desired icon.
iconFamily: A handle to the iconFamily data structure to register.
theIconRef: On return, a pointer to the desired icon data.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

Consider using the function RegisterIconRefFromIconFile, since the data registered using the RegisterIconRefFromIconFamily function cannot be purged. You are responsible for disposing of the IconRef by using the function ReleaseIconRef.

Calling this function increments the reference count of the IconRef.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

ReleaseIconRef

Decrements the reference count for an IconRef.

OSErr ReleaseIconRef (
   IconRef theIconRef
);

Parameters

theIconRef: An IconRef whose reference count you wish to decrement.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

RemoveIconRefOverride

Restores the original bitmaps of an overridden IconRef.

OSErr RemoveIconRefOverride (
   IconRef theIconRef
);

Parameters

theIconRef: A pointer to a value of type IconRef whose bitmaps are to be restored.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

SetCustomIconsEnabled

Enables or disables custom icons on a specified volume.

OSErr SetCustomIconsEnabled (
   SInt16 vRefNum,
   Boolean enableCustomIcons
);

Parameters

vRefNum: The volume where custom icons are to be enabled or disabled.
enableCustomIcons: If you pass true, custom icons are enabled on the volume specified. Passing false disables custom icons on the volume specified.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

If you use the SetCustomIconsEnabled function to enable or disable custom icons, the setting remains in effect only as long as the specified volume remains mounted during the current session.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

SetIconFamilyData

Provides new raw icon data for an individual element of an icon family.

OSErr SetIconFamilyData (
   IconFamilyHandle iconFamily,
   OSType iconType,
   Handle h
);

Parameters

iconFamily: A handle to an iconFamily data structure to be used as the target.
iconType: The format of the icon data you provide.You may specify one of the icon types (as defined in IconStorage.h in the CoreServices/OSServices framework) or 'PICT' in this parameter. For a thumbnail icon, for example, you specify kThumbnail32BitData in this parameter. For a thumbnail mask, you specify kThumbnail8BitMask.
h: A handle to the icon data you provide. For a thumbnail icon, the handle contains raw image data in the form of 128x128, four bytes per pixel, RGB data. For a thumbnail mask, the data is in the same format except that it is one byte per pixel.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

UnregisterIconRef

Removes the specified icon data from the icon registry.

OSErr UnregisterIconRef (
   OSType creator,
   OSType iconType
);

Parameters

creator: The creator code of the icon data to be unregistered.
iconType: The type code of the icon data to be unregistered.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

The specified icon data is not unregistered until all its users have called the function ReleaseIconRef.

You should not unregister an icon that you have not registered.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

UpdateIconRef

Forces an update of IconRef data.

OSErr UpdateIconRef (
   IconRef theIconRef
);

Parameters

theIconRef: An IconRef to be updated.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

This function is useful after you have changed a file or folder’s custom icon, for example. Do not call the UpdateIconRef function if you have not already obtained an IconRef for a particular icon; call the function GetIconRefFromFile instead.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

Callbacks

IconActionProcPtr

Defines a pointer to an icon action callback function, which performs an action on a single icon.

typedef OSErr (*IconActionProcPtr) (
   ResType theType,
   Handle *theIcon,
   void *yourDataPtr
);

If you name your function MyIconActionProc, you would declare it like this:

OSErr MyIconActionProc (
   ResType theType,
   Handle *theIcon,
   void *yourDataPtr
);

Parameters

theType: The resource type of the icon.
theIcon: A pointer to the handle to the icon on which to perform the operation.
yourDataPtr: A pointer to data as specified in the yourDataPtr parameter of the ForEachIconDo function. When your application calls ForEachIconDo, it typically provides in the yourDataPtr parameter a value that identifies the action your function should perform.

Return Value

A result code. See “Icon Services and Utilities Result Codes.”

Discussion

You can perform operations on every icon in an icon suite by providing a pointer to an icon action function as a parameter to the ForEachIconDo function. The ForEachIconDo function calls your icon action function for specified icon resource types. Your icon action function should return a result code indicating whether it successfully performed the action on the icon.

Before using your icon action function, you must first create a new universal procedure pointer to it, using the NewIconActionUPP function, as shown here:

IconActionUPP MyIconActionUPP;

MyIconActionUPP = NewIconActionUPP(&MyIconActionProc)

You then pass MyIconActionUPP to the ForEachIconDo function. When you are finished with your icon action callback function, you should dispose of the universal procedure pointer associated with it:

DisposeIconActionUPP(MyIconActionUPP);

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

IconGetterProcPtr

Defines a pointer to an icon getter callback function, which retrieves a handle to an icon of the requested type.

typedef Handle (*IconGetterProcPtr) (
   ResType theType,
   void *yourDataPtr
);

If you name your function MyIconGetterProc, you would declare it like this:

Handle MyIconGetterProc (
   ResType theType,
   void *yourDataPtr
);

Parameters

theType: The resource type of the icon. In general, you should specify your icon resources as purgeable.
yourDataPtr: If your icon getter function was called by an icon cache function, this parameter contains, on return, a pointer to the data associated with the icon cache. Otherwise, this parameter contains the value your application specified in the yourDataPtr parameter. For icon caches, you initially set this value when you first create a cache using the MakeIconCache function. You can change this value using the SetIconCacheData function. The icon getter function can use this data as needed.

Return Value

An icon getter function should return as its function result a handle to the requested icon’s data.

Discussion

If you use icon caches, you must provide at least one icon getter function. The MakeIconCache function takes a pointer to an icon getter function for use with a new icon cache. Subsequent calls to Icon Utilities functions that use icon types not present in the icon cache use the icon getter function associated with the icon cache to return a handle to the icon data. To get and set an existing icon cache’s icon getter function, use the GetIconCacheProc and SetIconCacheProc functions.

You can also specify an icon getter function for use by the PlotIconMethod, IconMethodToRgn, PtInIconMethod, and RectInIconMethod functions. Like Icon Utilities functions that work with icon caches, the icon getter function that you provide as a parameter to PlotIconMethod should return a handle to the requested icon’s data. Note that the icon getter function that you provide as a parameter to IconMethodToRgn, PtInIconMethod, and RectInIconMethod should also return a handle to the requested icon; these three functions then extract the icon mask from the icon data your icon getter function returns.

Before using your icon getter function, you must first create a new universal procedure pointer to it, using the NewIconGetterUPP function, as shown here:

IconGetterUPP MyIconGetterUPP;

MyIconGetterUPP = NewIconGetterUPP(&MyIconGetterProc)

You can then pass MyIconGetterUPP to any of the Icon Utilities functions which use custom icon getter functions. When you are finished with your icon getter callback function, you should dispose of the universal procedure pointer associated with it, using the DisposeIconGetterUPP function:

DisposeIconGetterUPP(MyIconGetterUPP);

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

Data Types

CIcon

Defines a color icon structure.

struct CIcon {
   PixMap iconPMap;
   BitMap iconMask;
   BitMap iconBMap;
   Handle iconData;
   SInt16 iconMaskData[1];
};
typedef struct CIcon CIcon;
typedef CIcon * CIconPtr;

Fields

iconPMap: The pixel map describing the icon. Note that this is a pixel map record, not a handle to a pixel map record.
iconMask: A bitmap of the icon’s mask.
iconBMap: A bitmap of the icon.
iconData: A handle to the icon’s pixel image.
iconMaskData: An array containing the icon’s mask data followed by the icon’s bitmap data. This is used only when the icon is stored as a resource.

Discussion

The PlotCIcon, PlotCIconHandle, GetCIcon, and DisposeCIcon functions all use the CIconHandle data type to refer to a color icon structure. A color icon structure contains information about a color icon.

All color icon resources should be marked purgeable. You can use icons of resource type 'cicn' in menus the same way that you use resources of type 'ICON'. If a menu item specifies an icon number, the menu definition function first tries to load in a 'cicn' resource with the specified resource ID. If it doesn’t find one, the menu definition function tries to load in an 'ICON' resource with the same ID. The Dialog Manager also uses a 'cicn' resource instead of an 'ICON' resource if it finds one with the same resource ID.

Availability

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

Declared In

Icons.h

IconRef

Defines an icon reference.

typedef struct OpaqueIconRef * IconRef;

Discussion

An IconRef is a 32–bit values identifying cached icon data. IconRef 0 is invalid.

Availability

Available in Mac OS X v10.0 and later.

Declared In

IconsCore.h

IconActionUPP

Defines a universal procedure pointer (UPP) to an icon action callback function.

typedef IconActionProcPtr IconActionUPP;

Discussion

For more information, see the description of the IconActionProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

IconGetterUPP

Defines a universal procedure pointer to an icon getter callback function.

typedef IconGetterProcPtr IconGetterUPP;

Discussion

For more information, see the description of the IconGetterProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Icons.h

IconCacheRef

Defines a reference to an icon cache.

typedef Handle IconCacheRef;

Availability

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

Declared In

Icons.h

IconSuiteRef

Defines a reference to an icon suite.

typedef Handle IconSuiteRef;

Availability

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

Declared In

Icons.h

Constants

Icon Alignment Constants

Define constants that allow you to specify how to align an icon within its rectangle.

enum {
   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
};
typedef SInt16 IconAlignmentType;

Constants

kAlignNone

Use this value if you do not wish to specify a particular alignment.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignVerticalCenter

Use this value to center the icon vertically within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignTop

Use this value to top align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignBottom

Use this value to bottom align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignHorizontalCenter

Use this value to center the icon horizontally within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignAbsoluteCenter

Use this value to center the icon horizontally and vertically within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignCenterTop

Use this value to top align the icon and center it horizontally within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignCenterBottom

Use this value to bottom align the icon and center it horizontally within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignLeft

Use this value to left align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignCenterLeft

Use this value to left align the icon and center it vertically within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignTopLeft

Use this value to left and top align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignBottomLeft

Use this value to left and bottom align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignRight

Use this value to right align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignCenterRight

Use this value to right align the icon and center it vertically within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignTopRight

Use this value to right and top align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kAlignBottomRight

Use this value to right and bottom align the icon within the rectangle.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

Discussion

Icon Services and Utilities functions use the IconAlignmentType constants to determine how an icon is aligned within its bounding rectangle.

Icon Transformation Constants

Define values that Icon Services uses to report how an icon has been transformed after you call the function GetIconRefVariant.

enum {
   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
};
typedef SInt16 IconTransformType;

Discussion

The functions PlotIconIDPlotIconMethod, PlotIconHandle, PlotCIconHandle, PlotIconSuite, LoadIconCache and PlotSICNHandle use these constants to specify how an icon should be modified, if at all, when plotted.

Icon Selector Constants

Describe values that you can use to obtain information about the sizes and depths of icons available in a given icon family.

enum {
   kSelectorLarge1Bit = 0x00000001,
   kSelectorLarge4Bit = 0x00000002,
   kSelectorLarge8Bit = 0x00000004,
   kSelectorLarge32Bit = 0x00000008,
   kSelectorLarge8BitMask = 0x00000010,
   kSelectorSmall1Bit = 0x00000100,
   kSelectorSmall4Bit = 0x00000200,
   kSelectorSmall8Bit = 0x00000400,
   kSelectorSmall32Bit = 0x00000800,
   kSelectorSmall8BitMask = 0x00001000,
   kSelectorMini1Bit = 0x00010000,
   kSelectorMini4Bit = 0x00020000,
   kSelectorMini8Bit = 0x00040000,
   kSelectorHuge1Bit = 0x01000000,
   kSelectorHuge4Bit = 0x02000000,
   kSelectorHuge8Bit = 0x04000000,
   kSelectorHuge32Bit = 0x08000000,
   kSelectorHuge8BitMask = 0x10000000,
   kSelectorAllLargeData = 0x000000FF,
   kSelectorAllSmallData = 0x0000FF00,
   kSelectorAllMiniData = 0x00FF0000,
   kSelectorAllHugeData = 0xFF000000,
   kSelectorAll1BitData = kSelectorLarge1Bit | kSelectorSmall1Bit
| kSelectorMini1Bit | kSelectorHuge1Bit,
   kSelectorAll4BitData = kSelectorLarge4Bit | kSelectorSmall4Bit
| kSelectorMini4Bit | kSelectorHuge4Bit,
   kSelectorAll8BitData = kSelectorLarge8Bit | kSelectorSmall8Bit
| kSelectorMini8Bit | kSelectorHuge8Bit,
   kSelectorAll32BitData = kSelectorLarge32Bit | kSelectorSmall32Bit
| kSelectorHuge32Bit,
   kSelectorAllAvailableData = 0xFFFFFFFF
};
typedef UInt32 IconSelectorValue;

Constants

kSelectorLarge1Bit

Specify to include 'ICN#' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge4Bit

Specify to include 'icl4' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge8Bit

Specify to include 'icl8' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge32Bit

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge8BitMask

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall1Bit

Specify to include 'ics#' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall4Bit

Specify to include 'ics4' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall8Bit

Specify to include 'ics8' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall32Bit

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall8BitMask

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorMini1Bit

Specify to include 'icm#' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorMini4Bit

Specify to include 'icm4' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorMini8Bit

Specify to include 'icm8' resource.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge1Bit

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge4Bit

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge8Bit

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge32Bit

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge8BitMask

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllLargeData

Specify to include 'ICN#', 'icl4', and 'icl8' resources.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllSmallData

Specify to include 'ics#', 'ics4', and 'ics8' resources.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllMiniData

Specify to include 'icm#', 'icm4', and 'icm8' resources.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllHugeData

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll1BitData

Specify to include 'ICN#', 'ics#', and 'icm#' resources.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll4BitData

Specify to include 'icl4', 'ics4', and 'icm4' resources.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll8BitData

Specify to include 'icl8', 'ics8', and 'icm8' resources.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll32BitData

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllAvailableData

Specify to include all resources of given ID.

Available in Mac OS X v10.0 and later.

Declared in Icons.h.

Discussion

The functions GetIconSuite and ForEachIconDo use these constants in the selector parameter to specify which members of the family to include in the icon suite.

Catalog Information Bitmask

Defines a minimal bitmask for use with the GetIconRefFromFileInfo function.

enum {
   kIconServicesCatalogInfoMask =
   (kFSCatInfoNodeID | kFSCatInfoParentDirID | kFSCatInfoVolume
   | kFSCatInfoNodeFlags | kFSCatInfoFinderInfo |
   kFSCatInfoFinderXInfo | kFSCatInfoUserAccess)
};

Constants

kIconServicesCatalogInfoMask

Use this mask with the File Manager function FSGetCatalogInfo before calling GetIconRefFromFileInfo.

Available in Mac OS X v10.1 and later.

Declared in IconsCore.h.

System Icon Constant

Defines a creator type for all system–defined icons.

enum {
   kSystemIconsCreator = 'macs'
};

Discussion

You can use the kSystemIconsCreator constant to obtain System icons that are not associated with a file, such as the help icon.

Icon Services Usage Flag

typedef UInt32 IconServicesUsageFlags;
enum {
   kIconServicesNormalUsageFlag = 0
};

Alert Icon Constants

Specify standard alert icons.

enum {
   kAlertNoteIcon = 'note',
   kAlertCautionIcon = 'caut',
   kAlertStopIcon = 'stop'
};

Discussion

Icon Services defines constants for a number of standard alert icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Filesharing Privilege Icon Constants

Identify standard filesharing privilege icons.

enum {
   kSharingPrivsNotApplicableIcon = 'shna',
   kSharingPrivsReadOnlyIcon = 'shro',
   kSharingPrivsReadWriteIcon = 'shrw',
   kSharingPrivsUnknownIcon = 'shuk',
   kSharingPrivsWritableIcon = 'writ'
};

Discussion

Icon Services defines constants for a number of standard filesharing privilege icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Folder Icon Constants

Identify standard folder icons.

enum {
   kGenericFolderIcon = 'fldr',
   kDropFolderIcon = 'dbox',
   kMountedFolderIcon = 'mntd',
   kOpenFolderIcon = 'ofld',
   kOwnedFolderIcon = 'ownd',
   kPrivateFolderIcon = 'prvf',
   kSharedFolderIcon = 'shfl'
};

Discussion

Icon Services defines constants for a number of standard folder icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Internet Icon Constants

Identify standard Internet icons.

enum {
   kInternetLocationHTTPIcon = 'ilht',
   kInternetLocationFTPIcon = 'ilft',
   kInternetLocationAppleShareIcon = 'ilaf',
   kInternetLocationAppleTalkZoneIcon = 'ilat',
   kInternetLocationFileIcon = 'ilfi',
   kInternetLocationMailIcon = 'ilma',
   kInternetLocationNewsIcon = 'ilnw',
   kInternetLocationNSLNeighborhoodIcon = 'ilns',
   kInternetLocationGenericIcon = 'ilge'
};

Discussion

Icon Services defines constants for a number of standard Internet icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Toolbar Icons

Identify standard toolbar icons.

enum {
   kToolbarCustomizeIcon = 'tcus',
   kToolbarDeleteIcon = 'tdel',
   kToolbarFavoritesIcon = 'tfav',
   kToolbarHomeIcon = 'thom'
};

Miscellaneous Icon Constants

Identify miscellaneous icons.

enum {
   kAppleLogoIcon = 'capl',
   kAppleMenuIcon = 'sapl',
   kBackwardArrowIcon = 'baro',
   kFavoriteItemsIcon = 'favr',
   kForwardArrowIcon = 'faro',
   kGridIcon = 'grid',
   kHelpIcon = 'help',
   kKeepArrangedIcon = 'arng',
   kLockedIcon = 'lock',
   kNoFilesIcon = 'nfil',
   kNoFolderIcon = 'nfld',
   kNoWriteIcon = 'nwrt',
   kProtectedApplicationFolderIcon = 'papp',
   kProtectedSystemFolderIcon = 'psys',
   kRecentItemsIcon = 'rcnt',
   kShortcutIcon = 'shrt',
   kSortAscendingIcon = 'asnd',
   kSortDescendingIcon = 'dsnd',
   kUnlockedIcon = 'ulck',
   kConnectToIcon = 'cnct',
   kGenericWindowIcon = 'gwin',
   kQuestionMarkIcon = 'ques',
   kDeleteAliasIcon = 'dali',
   kEjectMediaIcon = 'ejec',
   kBurningIcon = 'burn',
   kRightContainerArrowIcon = 'rcar'
};

Discussion

Icon Services defines constants for a number of miscellaneous icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Networking Icon Constants

Identify standard networking icons.

enum {
   kAppleTalkIcon = 'atlk',
   kAppleTalkZoneIcon = 'atzn',
   kAFPServerIcon = 'afps',
   kFTPServerIcon = 'ftps',
   kHTTPServerIcon = 'htps',
   kGenericNetworkIcon = 'gnet',
   kIPFileServerIcon = 'isrv'
};

Discussion

Icon Services defines constants for a number of standard networking icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Special Folder Icon Constants

Identify special folder icons.

enum {
   kAppearanceFolderIcon = 'appr',
   kAppleExtrasFolderIcon = 'aexƒ',
   kAppleMenuFolderIcon = 'amnu',
   kApplicationsFolderIcon = 'apps',
   kApplicationSupportFolderIcon = 'asup',
   kAssistantsFolderIcon = 'astƒ',
   kColorSyncFolderIcon = 'prof',
   kContextualMenuItemsFolderIcon = 'cmnu',
   kControlPanelDisabledFolderIcon = 'ctrD',
   kControlPanelFolderIcon = 'ctrl',
   kControlStripModulesFolderIcon = 'sdvƒ',
   kDocumentsFolderIcon = 'docs',
   kExtensionsDisabledFolderIcon = 'extD',
   kExtensionsFolderIcon = 'extn',
   kFavoritesFolderIcon = 'favs',
   kFontsFolderIcon = 'font',
   kHelpFolderIcon = 'ƒhlp',
   kInternetFolderIcon = 'intƒ',
   kInternetPlugInFolderIcon = 'ƒnet',
   kInternetSearchSitesFolderIcon = 'issf',
   kLocalesFolderIcon = 'ƒloc',
   kMacOSReadMeFolderIcon = 'morƒ',
   kPublicFolderIcon = 'pubf',
   kPreferencesFolderIcon = 'prfƒ',
   kPrinterDescriptionFolderIcon = 'ppdf',
   kPrinterDriverFolderIcon = 'ƒprd',
   kPrintMonitorFolderIcon = 'prnt',
   kRecentApplicationsFolderIcon = 'rapp',
   kRecentDocumentsFolderIcon = 'rdoc',
   kRecentServersFolderIcon = 'rsrv',
   kScriptingAdditionsFolderIcon = 'ƒscr',
   kSharedLibrariesFolderIcon = 'ƒlib',
   kScriptsFolderIcon = 'scrƒ',
   kShutdownItemsDisabledFolderIcon = 'shdD',
   kShutdownItemsFolderIcon = 'shdf',
   kSpeakableItemsFolder = 'spki',
   kStartupItemsDisabledFolderIcon = 'strD',
   kStartupItemsFolderIcon = 'strt',
   kSystemExtensionDisabledFolderIcon = 'macD',
   kSystemFolderIcon = 'macs',
   kTextEncodingsFolderIcon = 'ƒtex',
   kUsersFolderIcon = 'usrƒ',
   kUtilitiesFolderIcon = 'utiƒ',
   kVoicesFolderIcon = 'fvoc'
};

Discussion

Icon Services defines constants for a number of special folder icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Standard Finder Icon Constants

Identify standard Finder icons.

enum {
   kClipboardIcon = 'CLIP',
   kClippingUnknownTypeIcon = 'clpu',
   kClippingPictureTypeIcon = 'clpp',
   kClippingTextTypeIcon = 'clpt',
   kClippingSoundTypeIcon = 'clps',
   kDesktopIcon = 'desk',
   kFinderIcon = 'FNDR',
   kFontSuitcaseIcon = 'FFIL',
   kFullTrashIcon = 'ftrh',
   kGenericApplicationIcon = 'APPL',
   kGenericCDROMIcon = 'cddr',
   kGenericControlPanelIcon = 'APPC',
   kGenericControlStripModuleIcon = 'sdev',
   kGenericComponentIcon = 'thng',
   kGenericDeskAccessoryIcon = 'APPD',
   kGenericDocumentIcon = 'docu',
   kGenericEditionFileIcon = 'edtf',
   kGenericExtensionIcon = 'INIT',
   kGenericFileServerIcon = 'srvr',
   kGenericFontIcon = 'ffil',
   kGenericFontScalerIcon = 'sclr',
   kGenericFloppyIcon = 'flpy',
   kGenericHardDiskIcon = 'hdsk',
   kGenericIDiskIcon = 'idsk',
   kGenericRemovableMediaIcon = 'rmov',
   kGenericMoverObjectIcon = 'movr',
   kGenericPCCardIcon = 'pcmc',
   kGenericPreferencesIcon = 'pref',
   kGenericQueryDocumentIcon = 'qery',
   kGenericRAMDiskIcon = 'ramd',
   kGenericSharedLibaryIcon = 'shlb',
   kGenericStationeryIcon = 'sdoc',
   kGenericSuitcaseIcon = 'suit',
   kGenericURLIcon = 'gurl',
   kGenericWORMIcon = 'worm',
   kInternationalResourcesIcon = 'ifil',
   kKeyboardLayoutIcon = 'kfil',
   kSoundFileIcon = 'sfil',
   kSystemSuitcaseIcon = 'zsys',
   kTrashIcon = 'trsh',
   kTrueTypeFontIcon = 'tfil',
   kTrueTypeFlatFontIcon = 'sfnt',
   kTrueTypeMultiFlatFontIcon = 'ttcf',
   kUserIDiskIcon = 'udsk',
   kUnknownFSObjectIcon = 'unfs',
   kInternationResourcesIcon = kInternationalResourcesIcon
};

Discussion

Icon Services defines constants for a number of standard Finder icons. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Standard Icon Badge Constants

Identify standard badges.

enum {
   kAppleScriptBadgeIcon = 'scrp',
   kLockedBadgeIcon = 'lbdg',
   kMountedBadgeIcon = 'mbdg',
   kSharedBadgeIcon = 'sbdg',
   kAliasBadgeIcon = 'abdg',
   kAlertCautionBadgeIcon = 'cbdg'
};

Discussion

Icon Services defines constants for a number of standard badges. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

Users and Groups Icon Constants

Identify icons used in the Users and Groups control panel.

enum {
   kUserFolderIcon = 'ufld',
   kWorkgroupFolderIcon = 'wfld',
   kGuestUserIcon = 'gusr',
   kUserIcon = 'user',
   kOwnerIcon = 'susr',
   kGroupIcon = 'grup'
};

Discussion

Icon Services defines constants for a number of icons used in the Users and Groups control panel. You can pass one of these constants in the iconType parameter of the function GetIconRef, for example.

genericDocumentIconResource

Use the constants listed in "Standard Icon Resources" instead.

enum {
   genericDocumentIconResource = kGenericDocumentIconResource,
   genericStationeryIconResource = kGenericStationeryIconResource,
   genericEditionFileIconResource = kGenericEditionFileIconResource,
   genericApplicationIconResource = kGenericApplicationIconResource,
   genericDeskAccessoryIconResource = kGenericDeskAccessoryIconResource,
   genericFolderIconResource = kGenericFolderIconResource,
   privateFolderIconResource = kPrivateFolderIconResource,
   floppyIconResource = kFloppyIconResource,
   trashIconResource = kTrashIconResource,
   genericRAMDiskIconResource = kGenericRAMDiskIconResource,
   genericCDROMIconResource = kGenericCDROMIconResource,
   desktopIconResource = kDesktopIconResource,
   openFolderIconResource = kOpenFolderIconResource,
   genericHardDiskIconResource = kGenericHardDiskIconResource,
   genericFileServerIconResource = kGenericFileServerIconResource,
   genericSuitcaseIconResource = kGenericSuitcaseIconResource,
   genericMoverObjectIconResource = kGenericMoverObjectIconResource,
   genericPreferencesIconResource = kGenericPreferencesIconResource,
   genericQueryDocumentIconResource = kGenericQueryDocumentIconResource,
   genericExtensionIconResource = kGenericExtensionIconResource,
   systemFolderIconResource = kSystemFolderIconResource,
   appleMenuFolderIconResource = kAppleMenuFolderIconResource
};

Standard Icon Resources

Identify standard icon resources.

/*Icons for which both icon suites and 'SICN' resources exist*/
enum {
   kGenericDocumentIconResource = -4000,
   kGenericStationeryIconResource = -3985,
   kGenericEditionFileIconResource = -3989,
   kGenericApplicationIconResource = -3996,
   kGenericDeskAccessoryIconResource = -3991,
   kGenericFolderIconResource = -3999,
   kPrivateFolderIconResource = -3994,
   kFloppyIconResource = -3998,
   kTrashIconResource = -3993,
   kGenericRAMDiskIconResource = -3988,
   kGenericCDROMIconResource = -3987
};
/* Icons for which only 'SICN' resources exist*/
enum {
   kDesktopIconResource = -3992,
   kOpenFolderIconResource = -3997,
   kGenericHardDiskIconResource = -3995,
   kGenericFileServerIconResource = -3972,
   kGenericSuitcaseIconResource = -3970,
   kGenericMoverObjectIconResource = -3969
};
/*Icons for which only icon suites exist*/
enum {
   kGenericPreferencesIconResource = -3971,
   kGenericQueryDocumentIconResource = -16506,
   kGenericExtensionIconResource = -16415,
   kSystemFolderIconResource = -3983,
   kHelpIconResource = -20271,
   kAppleMenuFolderIconResource = -3982
};
enum {
   kStartupFolderIconResource = -3981,
   kOwnedFolderIconResource = -3980,
   kDropFolderIconResource = -3979,
   kSharedFolderIconResource = -3978,
   kMountedFolderIconResource = -3977,
   kControlPanelFolderIconResource = -3976,
   kPrintMonitorFolderIconResource = -3975,
   kPreferencesFolderIconResource = -3974,
   kExtensionsFolderIconResource = -3973,
   kFontsFolderIconResource = -3968,
   kFullTrashIconResource = -3984
};

startupFolderIconResource

Use the constants described in "Standard Icon Resources" instead.

enum {
   startupFolderIconResource = kStartupFolderIconResource,
   ownedFolderIconResource = kOwnedFolderIconResource,
   dropFolderIconResource = kDropFolderIconResource,
   sharedFolderIconResource = kSharedFolderIconResource,
   mountedFolderIconResource = kMountedFolderIconResource,
   controlPanelFolderIconResource = kControlPanelFolderIconResource,
   printMonitorFolderIconResource = kPrintMonitorFolderIconResource,
   preferencesFolderIconResource = kPreferencesFolderIconResource,
   extensionsFolderIconResource = kExtensionsFolderIconResource,
   fontsFolderIconResource = kFontsFolderIconResource,
   fullTrashIconResource = kFullTrashIconResource
};

atNone

Use the constants described in "Icon Alignment Constants" instead.

enum {
   atNone = kAlignNone,
   atVerticalCenter = kAlignVerticalCenter,
   atTop = kAlignTop,
   atBottom = kAlignBottom,
   atHorizontalCenter = kAlignHorizontalCenter,
   atAbsoluteCenter = kAlignAbsoluteCenter,
   atCenterTop = kAlignCenterTop,
   atCenterBottom = kAlignCenterBottom,
   atLeft = kAlignLeft,
   atCenterLeft = kAlignCenterLeft,
   atTopLeft = kAlignTopLeft,
   atBottomLeft = kAlignBottomLeft,
   atRight = kAlignRight,
   atCenterRight = kAlignCenterRight,
   atTopRight = kAlignTopRight,
   atBottomRight = kAlignBottomRight
};

svLarge1Bit

Use the constants described in "Icon Selector Constants" instead.

enum {
   svLarge1Bit = kSelectorLarge1Bit,
   svLarge4Bit = kSelectorLarge4Bit,
   svLarge8Bit = kSelectorLarge8Bit,
   svSmall1Bit = kSelectorSmall1Bit,
   svSmall4Bit = kSelectorSmall4Bit,
   svSmall8Bit = kSelectorSmall8Bit,
   svMini1Bit = kSelectorMini1Bit,
   svMini4Bit = kSelectorMini4Bit,
   svMini8Bit = kSelectorMini8Bit,
   svAllLargeData = kSelectorAllLargeData,
   svAllSmallData = kSelectorAllSmallData,
   svAllMiniData = kSelectorAllMiniData,
   svAll1BitData = kSelectorAll1BitData,
   svAll4BitData = kSelectorAll4BitData,
   svAll8BitData = kSelectorAll8BitData,
   svAllAvailableData = kSelectorAllAvailableData
};

ttNone

Use the constants described in "Icon Transformation Constants" instead.

enum {
   ttNone = kTransformNone,
   ttDisabled = kTransformDisabled,
   ttOffline = kTransformOffline,
   ttOpen = kTransformOpen,
   ttLabel1 = kTransformLabel1,
   ttLabel2 = kTransformLabel2,
   ttLabel3 = kTransformLabel3,
   ttLabel4 = kTransformLabel4,
   ttLabel5 = kTransformLabel5,
   ttLabel6 = kTransformLabel6,
   ttLabel7 = kTransformLabel7,
   ttSelected = kTransformSelected,
   ttSelectedDisabled = kTransformSelectedDisabled,
   ttSelectedOffline = kTransformSelectedOffline,
   ttSelectedOpen = kTransformSelectedOpen
};

Result Codes

The table below shows the most common result codes returned by Icon Services and Utilities.

Result Code	Value	Description
`noMaskFoundErr`	-1000	Available in Mac OS X v10.0 and later.
`invalidIconRefErr`	-2580	The `IconRef` is not valid. Available in Mac OS X v10.0 and later.
`noSuchIconErr`	-2581	The requested icon could not be found. Available in Mac OS X v10.0 and later.
`noIconDataAvailableErr`	-2582	The necessary icon data is not available. Available in Mac OS X v10.0 and later.

Gestalt Constants

You can check for version and feature availability information by using the Icon Services selectors defined in the Gestalt Manager. For more information, see Gestalt Manager Reference.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.