Icon Services and Utilities Reference (Legacy)

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 OS X v10.0 and later.
Related Sample Code
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 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 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 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 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 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 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 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.

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 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 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.

Discussion

Typically, you do not need to use this function.

Availability
  • Available in 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.

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 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 OS X v10.0 and later.
Related Sample Code
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 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 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 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

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 returns the shape of the mask.

Availability
  • Available in 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 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 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 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 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 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 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 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 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 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 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 OS X v10.1 and later.
Related Sample Code
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 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 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 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

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 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 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 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 OS X v10.0 and later.
Related Sample Code
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 OS X v10.0 and later.
Related Sample Code
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 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 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 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 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 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 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 OS X v10.0 and later.
Declared In
Icons.h

IconCacheRef

Defines a reference to an icon cache.

typedef Handle IconCacheRef;
Availability
  • Available in 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 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 OS X v10.0 and later.

Declared in Icons.h.

kAlignVerticalCenter

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kAlignTop

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kAlignBottom

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kAlignHorizontalCenter

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

Available in 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 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 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 OS X v10.0 and later.

Declared in Icons.h.

kAlignLeft

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

Available in 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 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 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 OS X v10.0 and later.

Declared in Icons.h.

kAlignRight

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

Available in 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 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 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 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 OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge4Bit

Specify to include 'icl4' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge8Bit

Specify to include 'icl8' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge32Bit

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorLarge8BitMask

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall1Bit

Specify to include 'ics#' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall4Bit

Specify to include 'ics4' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall8Bit

Specify to include 'ics8' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall32Bit

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorSmall8BitMask

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorMini1Bit

Specify to include 'icm#' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorMini4Bit

Specify to include 'icm4' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorMini8Bit

Specify to include 'icm8' resource.

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge1Bit

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge4Bit

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge8Bit

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge32Bit

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorHuge8BitMask

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllLargeData

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllSmallData

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllMiniData

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllHugeData

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll1BitData

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll4BitData

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll8BitData

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

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAll32BitData

Available in OS X v10.0 and later.

Declared in Icons.h.

kSelectorAllAvailableData

Specify to include all resources of given ID.

Available in 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 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 CodeValueDescription
noMaskFoundErr -1000

Available in OS X v10.0 and later.

invalidIconRefErr -2580

The IconRef is not valid.

Available in OS X v10.0 and later.

noSuchIconErr -2581

The requested icon could not be found.

Available in OS X v10.0 and later.

noIconDataAvailableErr -2582

The necessary icon data is not available.

Available in 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.