ADC Home > Reference Library > Reference > Carbon > User Experience > Icon Services and Utilities Reference >

< Previous PageNext Page > Hide TOC

Deprecated Icon Services and Utilities Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.3

FlushIconRefs

Reclaims memory used by the specified icon if the memory is purgeable. (Deprecated in Mac OS X v10.3. There is no replacement; this function was included to facilitate porting classic applications to Carbon, but it serves no useful purpose in Mac OS X.)

OSErr FlushIconRefs (
   OSType creator,
   OSType iconType
);

Parameters
creator

The creator code of the file whose icon data is to be flushed.

iconType

The type code of the file whose icon data is to be flushed.

Return Value

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

Special Considerations

This function does nothing in Mac OS X.

Availability
Declared In
IconsCore.h

FlushIconRefsByVolume

On a given volume, reclaims memory used by purgeable icons. (Deprecated in Mac OS X v10.3. There is no replacement; this function was included to facilitate porting classic applications to Carbon, but it serves no useful purpose in Mac OS X.)

OSErr FlushIconRefsByVolume (
   SInt16 vRefNum
);

Parameters
vRefNum

The volume whose icon cache is to be flushed.

Return Value

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

Discussion

Calling this function locks the bitmap data of all IconRefs with non-zero reference counts (that is, all IconRefs that are in use) on the volume. The Finder normally maintains a number of IconRefs with non-zero reference counts, so you should use the function FlushIconRefs instead of the FlushIconRefsByVolume function whenever feasible.

Special Considerations

This function does nothing in Mac OS X.

Availability
Declared In
IconsCore.h

GetIconSizesFromIconRef

Provides an IconSelectorValue indicating the sizes and depths of icon data available for an IconRef. (Deprecated in Mac OS X v10.3. Use IsDataAvailableInIconRef instead.)

OSErr GetIconSizesFromIconRef (
   IconSelectorValue iconSelectorInput,
   IconSelectorValue *iconSelectorOutputPtr,
   IconServicesUsageFlags iconServicesUsageFlags,
   IconRef theIconRef
);

Parameters
iconSelectorInput

The icon sizes and depths you are requesting from the IconRef. For a description of the possible values, see “Icon Selector Constants.”

iconSelectorOutputPtr

On return, this points to a value describing the icon sizes and depths available for the specified IconRef. For a description of the possible values, see “Icon Selector Constants.”

iconServicesUsageFlags

Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.

theIconRef

The icon family to query.

Return Value

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

Discussion

Note that this function may be very time-consuming, as Icon Services may have to search disks or even the network to obtain the requested data.

Special Considerations

Because this function is so time-consuming, it is more efficient to simply query the icon for particular data using the function IsDataAvailableInIconRef.

Availability
Declared In
Icons.h

Deprecated in Mac OS X v10.5

AddIconToSuite

Adds an icon to an icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr AddIconToSuite (
   Handle theIconData,
   IconSuiteRef theSuite,
   ResType theType
);

Parameters
theIconData

A handle to the data for the new icon to be added to the icon suite. You can obtain a handle to icon data using various functions, such as GetIcon or GetResource.

The handle to the icon data is added at the location reserved for icon data of the type specified by theType. If the icon suite already includes a handle to icon data for that type, this function replaces the handle to the old data without disposing of it. In this case you may want to call the GetIconFromSuite function first to obtain the old handle so that you can dispose of it.

The handles that you add to the suite do not have to be associated with a resource fork. For example, your application might get icon data from the desktop database rather than reading it from a resource, or your application might read icon data from a resource and then detach it.

theSuite

A handle to the icon suite to which to add the icon.

theType

The resource type of the new icon. The resource type should be that of an icon family member.

Return Value

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

Discussion

This function is most often used to read icons into an empty icon suite created with the NewIconSuite function.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

DisposeCIcon

Releases the memory occupied by a color icon structure. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

void DisposeCIcon (
   CIconHandle theIcon
);

Parameters
theIcon

A handle to the color icon structure to dispose of, previously obtained from the GetCIcon function.

Discussion

To dispose of a handle obtained from GetIcon or GetResource, use the ReleaseResource function to release the memory occupied by the icon resource data.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

DisposeIconSuite

Releases the memory occupied by an icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr DisposeIconSuite (
   IconSuiteRef theIconSuite,
   Boolean disposeData
);

Parameters
theIconSuite

A handle to the icon suite to be disposed of.

disposeData

A Boolean value indicating whether or not to dispose of handles in the icon suite that are not associated with a resource fork.

Set this value to TRUE to automatically release icon data that is associated with the specified icon suite but not explicitly associated with a resource fork. If you set this value to FALSE, the function does not dispose of any icon data that is associated with the specified icon suite.

Return Value

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

Discussion

This function does not release the memory of any icons explicitly associated with an open resource fork, that is, any handles to icon resource data that your application added to the suite using the functions GetIconSuite or AddIconToSuite. For handles to icon data that your application added to the icon suite using AddIconToSuite (for example, if your application read in an icon resource, detached it, then added the handle to the suite), you can request that AddIconToSuite release the memory associated with the handles.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

ForEachIconDo

Performs an action on one or more icons in an icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

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

Parameters
theSuite

A handle to an icon suite.

selector

Indicates which icons in the suite to perform the operation on. See “Icon Selector Constants” for a description of the values you can use in this parameter.

action

A universal procedure pointer to your icon action callback function. The ForEachIconDo function uses this icon action function to perform an action on the specified icons in the icon suite.

ForEachIconDo calls your icon action function once for each type of icon specified in the selector parameter. ForEachIconDo passes to your icon action function a handle to the icon to perform the action on. Your icon action function should perform any action as indicated by the yourDataPtr parameter and return a result code.

See the IconActionProcPtr callback for more information about icon action functions.

yourDataPtr

A pointer to data or other information required by your icon action function that is passed to your icon action function. Typically, you use this parameter to specify which action your icon action function should perform.

Return Value

A result code. See “Icon Services and Utilities Result Codes.” The result code returned by your icon action function. If your icon action function returns a nonzero function result, ForEachIconDo immediately returns to the application.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetCIcon

Gets a handle to a color icon of resource type 'cicn'. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

CIconHandle GetCIcon (
   SInt16 iconID
);

Parameters
iconID

The resource ID for an icon of resource type 'cicn'. In general, you should specify your icon resources as purgeable.

Return Value

A handle to the CIcon structure for the icon, or NULL if the function could not find the resource.

Discussion

The function searches the current resource chain for the resource. If it finds the resource, it reads the resource, creates a color icon structure for the icon, and initializes the fields of the structure according to the information contained in the 'cicn' resource.

To draw an icon obtained from this function in a specified rectangle, you can use either the PlotCIcon function, or the PlotCIconHandle function. The latter function allows you to specify transforms and alignments.

When you are finished with a handle obtained from this function, use the DisposeCIcon function to release the memory occupied by the color icon structure.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetIcon

Gets a handle to an icon resource of type 'ICON'. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Handle GetIcon (
   SInt16 iconID
);

Parameters
iconID

The resource ID for an icon of resource type 'ICON'. The function searches the current resource chain for the resource. In general, you should specify your icon resources as purgeable.

Return Value

A handle to the icon with the specified ID or NULL if the function could not find the resource.

Discussion

To draw an icon obtained from this function in a specified rectangle, you can use either the PlotIcon function, or the PlotIconHandle function. The latter function allows you to specify transforms and alignments.

When you are finished using a handle obtained from this function, use the ReleaseResource function to release the memory occupied by the icon resource data.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetIconCacheData

Gets the data associated with an icon cache. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr GetIconCacheData (
   IconCacheRef theCache,
   void **theData
);

Parameters
theCache

A handle to the icon cache whose data is desired.

theData

On return, a pointer to a pointer to the data associated with the icon cache.

You associate data with an icon cache when you first create the cache using the MakeIconCache function. You can also set this data using the SetIconCacheData function.

Return Value

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

Discussion

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetIconCacheProc

Gets the icon getter function associated with an icon cache. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr GetIconCacheProc (
   IconCacheRef theCache,
   IconGetterUPP *theProc
);

Parameters
theCache

A handle to the icon cache whose associated icon getter function is desired.

theProc

On return, a pointer to the universal procedure pointer to the icon getter callback function associated with the specified cache. See the IconGetterProcPtr callback for more information on icon getter functions.

Return Value

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

Discussion

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache. An icon cache is like an icon suite except that it also contains a pointer to an icon getter callback function and a pointer to data that can be used as a reference constant. An icon cache typically does not contain handles to the icon resources for all icon family members. Instead, if the icon cache does not contain an entry for a specific type of icon in an icon family, the Icon Utilities functions call your application’s icon getter function to retrieve the data for that icon type.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetIconFromSuite

Gets an icon from an icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

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

Parameters
theIconData

On return, a pointer to a handle to the data for the requested icon. If an icon of the specified type does not exist in the given icon suite, this parameter is NULL.

If you intend to dispose of the handle, pass a NULL handle to the AddIconToSuite function to delete the corresponding entry in the suite.

You can use the handle returned by this function to manipulate the icon data, for example, to alter its color or add three-dimensional shading. However, you should not use the returned handle to draw the icon with other Icon Utilities functions.

To plot an icon from an icon suite, you should normally use the PlotIconSuite function. The PlotIconHandle function may not draw the icon correctly if you pass it the handle returned in this parameter.

theSuite

A handle to the icon suite from which to get the icon.

theType

The resource type of the desired icon.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetIconRefFromFile

Provides an IconRef object for a file, folder or volume. (Deprecated in Mac OS X v10.5. Use GetIconRefFromFileInfo instead.)

OSErr GetIconRefFromFile (
   const FSSpec *theFile,
   IconRef *theIconRef,
   SInt16 *theLabel
);

Parameters
theFile

A pointer to the FSSpec structure specifying the file, folder or volume for the IconRef.

theIconRef

On return, a pointer to an IconRef object. You are responsible for releasing the object by calling ReleaseIconRef.

theLabel

On return, a pointer to the file or folder’s label.

Return Value

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

Discussion

Use this function if you have no information about the file object passed in the theFile parameter. If you have already called the File System Manager function PBGetCatInfo, you can use the function GetIconRefFromFolder if the object is a folder without custom icons or the function GetIconRef if the object is a file without custom icons.

Availability
Declared In
IconsCore.h

GetIconSuite

Creates an icon suite in memory that contains handles to a specified icon family’s resources. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr GetIconSuite (
   IconSuiteRef *theIconSuite,
   SInt16 theResID,
   IconSelectorValue selector
);

Parameters
theIconSuite

On return, a pointer to a handle to an icon suite for the requested icon family, for which this function allocates the memory. To release the memory occupied by an icon suite, you must use the DisposeIconSuite function.

theResID

The resource ID of the icons in the icon family to be read into memory. In general, you should specify your icon resources as purgeable.

selector

Indicates which icons from the icon family to include in the icon suite. See “Icon Selector Constants” for a description of the values you can use in this parameter.

Return Value

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

Discussion

When you create an icon suite from icon family resources, the associated resource file should remain open while you use Icon Utilities functions. If you call the SetResLoad function with the load parameter set to FALSE before you call this function, the suite is filled with unloaded resource handles.

When you create an icon suite using this function, it sets the default label for the suite to none. To set a new default label for an icon suite, use the SetSuiteLabel function. To perform operations on one or more icons in an icon suite, use the ForEachIconDo function. To draw the icon described by the icon suite using the icon family member that is most suitable for the current bit depth of the display device, use the PlotIconSuite function.

As an alternative to this function, you can also create an empty icon suite using the NewIconSuite function and then add icons to it one at a time using the AddIconToSuite function.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetLabel

Gets the color and string used for a given label in the Label menu of the Finder and in the Labels control panel. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr GetLabel (
   SInt16 labelNumber,
   RGBColor *labelColor,
   Str255 labelString
);

Parameters
labelNumber

An integer from 1 to 7 indicating which label’s information is requested.

labelColor

On return, a pointer to the color of the specified label.

labelString

On return, the string associated with the specified label.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

GetSuiteLabel

Gets the default label setting associated with an icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

SInt16 GetSuiteLabel (
   IconSuiteRef theSuite
);

Parameters
theSuite

A handle to an icon suite.

Return Value

The default label setting associated with the specified icon suite. The default label setting is an integer from 1 to 7 that specifies which of the label colors shown in the Finder’s Label menu is applied to icons of that suite when your application displays them. The function returns 0 if the suite doesn’t have a label. You can override the default label setting for a suite by specifying a label in the transform parameter of the PlotIconSuite function. To get information about the color and string for a specific label, you can use the GetLabel function.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

IconFamilyToIconSuite

Provides icon suite data for a given icon family. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr IconFamilyToIconSuite (
   IconFamilyHandle iconFamily,
   IconSelectorValue whichIcons,
   IconSuiteRef *iconSuite
);

Parameters
iconFamily

A handle to an iconFamily data structure to use as a source for icon data. For more information on the IconFamily data structure, see 'icns'.

whichIcons

The depths and sizes of icons to extract from the IconFamily data structure. For a description of the possible values, see “Icon Selector Constants.”

iconSuite

On return, a pointer to the structure which contains icon data as specified in the iconFamily and whichIcons parameters. Icon Services returns NULL if no appropriate icon data is found.

Return Value

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

Availability
Declared In
Icons.h

IconIDToRgn

Converts the icon mask in an icon family to a region. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr IconIDToRgn (
   RgnHandle theRgn,
   const Rect *iconRect,
   IconAlignmentType align,
   SInt16 iconID
);

Parameters
theRgn

On return, a handle to the requested region. You must allocate memory for the region handle before calling this function.

The returned region corresponds to the icon’s mask (the mask defined by either an 'ICN#' or 'ics#' resource in an icon family, according to the rectangle and alignment specified in the iconRect and align parameters).

Once you have a region that describes the icon mask for a given icon, you can use it to perform accurate hit-testing and outline dragging of the icon in your application.

iconRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The function uses this rectangle as the bounding box of the region. The function determines, from the size of the rectangle specified here, which icon mask to use from the specified icon family.

align

Specifies how the function should align the mask within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

iconID

The resource ID of the icon for which to create a region. In general, you should specify your icon resources as purgeable.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

IconMethodToRgn

Converts, to a region, the mask for an icon that IconMethodToRgn obtains with the aid of your icon getter callback function. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr IconMethodToRgn (
   RgnHandle theRgn,
   const Rect *iconRect,
   IconAlignmentType align,
   IconGetterUPP theMethod,
   void *yourDataPtr
);

Parameters
theRgn

On return, a handle to the requested region. You must allocate memory for the region handle before calling this function. Once you have a region that describes the icon mask for a given icon, you can use it to perform accurate hit-testing and outline dragging of the icon in your application.

iconRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The function obtains the data for the icon mask from your icon getter function and then converts the icon mask to a region. The function uses the rectangle specified in this parameter as the bounding box of the region.

align

Specifies how the function should align the mask within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

theMethod

A universal procedure pointer to your icon getter callback function. IconMethodToRgn passes to your icon getter function the type of the icon to get and the value specified in the yourDataPtr parameter. The IconMethodToRgn function examines the size of the rectangle and requests the appropriate icon from your icon getter function—an icon of icon type 'ICN#' or 'ics#'. Your icon getter function should return a handle to the data of the requested icon type. The IconMethodToRgn function extracts the mask from the icon data that your icon getter function returns. If your icon getter function returns data that does not correspond to an icon of type 'ICN#' or type 'ics#', IconMethodToRgn attempts to generate a mask from the returned data.

Your icon getter function can get the data for the icon and its mask using whatever method is appropriate to your application. For example, your application might maintain its own cache of icons (and pass a pointer to it in the yourDataPtr parameter) or use its icon getter function to get an icon from the desktop database.

See the IconGetterProcPtr callback for more information on creating an icon getter function.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

IconRefToRgn

Converts an Icon Services icon into a QuickDraw region. (Deprecated in Mac OS X v10.5. Use IconRefToHIShape instead.)

OSErr IconRefToRgn (
   RgnHandle theRgn,
   const Rect *iconRect,
   IconAlignmentType align,
   IconServicesUsageFlags iconServicesUsageFlags,
   IconRef theIconRef
);

Parameters
theRgn

A handle to the requested region. You must call the QuickDraw function NewRegion to allocate memory for the region handle before calling the IconRefToRgn function.

iconRect

A pointer to the rectangle defining the area that Icon Services uses as the bounding box of the region.

align

The value which determines how Icon Services aligns the region within the rectangle. For a description of possible return values, see “Icon Alignment Constants.”

iconServicesUsageFlags

Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.

theIconRef

The IconRef for the icon family to use for drawing the requested region.

Return Value

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

Discussion

Icon Services uses the rectangle and alignment values to automatically select the icon used to generate the region data.

This function is similar to the Icon Utilities function IconSuiteToRegion.

Icon Services uses the icon’s black-and-white mask to determine the region data, even if you provide a deep mask.

Availability
Declared In
Icons.h

IconSuiteToIconFamily

Provides IconFamily data for a specified IconSuite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr IconSuiteToIconFamily (
   IconSuiteRef iconSuite,
   IconSelectorValue whichIcons,
   IconFamilyHandle *iconFamily
);

Parameters
iconSuite

The IconSuiteRef to use as a source for icon data.

whichIcons

The depths and sizes of icons to extract from 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 structure which contains icon data as specified in the iconSuite 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
Declared In
Icons.h

IconSuiteToRgn

Converts the icon mask in an icon suite to a region. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr IconSuiteToRgn (
   RgnHandle theRgn,
   const Rect *iconRect,
   IconAlignmentType align,
   IconSuiteRef theIconSuite
);

Parameters
theRgn

On return, a handle to the requested region. You must allocate memory for the region handle before calling this function.

The returned region corresponds to the icon’s mask (the mask defined by either an 'ICN#' or 'ics#' entry in an icon suite, according to the rectangle and alignment specified in the iconRect and align parameters).

Once you have a region that describes the icon mask for a given icon, you can use it to perform accurate hit-testing and outline dragging of the icon in your application.

iconRect

A pointer to the rectangle in which the icon is to be drawn, specified in local coordinates of the current graphics port. The function uses this rectangle as the bounding box of the region. The function determines, from the size of the rectangle specified here, which icon mask to use from the icon suite.

align

Specifies how the function should align the region within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

theIconSuite

A handle to an icon suite.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

LoadIconCache

Loads into an icon cache a handle to the appropriate icon data for a specified destination rectangle and the current bit depth, for drawing later with a specified alignment and transform. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr LoadIconCache (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   IconCacheRef theIconCache
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port. The function uses the rectangle specified in this parameter and the bit depth of the display device to determine which icon type to load into the cache.

align

Specifies how to align the icon within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

transform

Specifies how to modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use in this parameter.

theIconCache

A reference to the icon cache into which to load the icon data.

Return Value

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

Discussion

This function can be useful, for example, if you suspect that the icon may be drawn at a time not convenient for loading resource data (for instance, when the resource fork isn’t in the current resource chain). The function uses the same criteria as the PlotIconSuite function to select the icon to load.

This function uses the icon getter callback function associated with the icon cache to get the appropriate icon. The icon getter function returns a handle to the requested icon data, and LoadIconCache adds the returned handle to the entry for that icon in the icon cache.

After calling this function, you can pass the same parameters to PlotIconSuite to plot the icon data. Note that if you specify an alignment when you call LoadIconCache, then call PlotIconSuite and specify no alignment, PlotIconSuite draws the icon using the alignment that you originally specified to LoadIconCache.

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

MakeIconCache

Gets a handle to an empty icon cache. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr MakeIconCache (
   IconCacheRef *theCache,
   IconGetterUPP makeIcon,
   void *yourDataPtr
);

Parameters
theCache

On return, a pointer to a handle to the new, empty icon cache. The function allocates the necessary memory. You can add icon data to the new cache using the LoadIconCache function.

makeIcon

A universal procedure pointer to the icon getter callback function to associate with the icon cache. See the IconGetterProcPtr callback for more information on icon getter callback functions.

yourDataPtr

A pointer to the data to associate with the icon cache.

Return Value

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

Discussion

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache. An icon cache is like an icon suite except that it also contains a pointer to an icon getter callback function and a pointer to data that can be used as a reference constant. An icon cache typically does not contain handles to the icon resources for all icon family members. Instead, if the icon cache does not contain an entry for a specific type of icon in an icon family, the Icon Utilities functions call your application’s icon getter function to retrieve the data for that icon type.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

NewIconSuite

Gets a handle to an empty icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr NewIconSuite (
   IconSuiteRef *theIconSuite
);

Parameters
theIconSuite

On return, a pointer to a handle to a new, empty icon suite. Use the AddIconToSuite function to add handles to icon data.

Return Value

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

Discussion

When you create an icon suite using this function, it sets the default label for the suite to none. To set a new default label for an icon suite, use the SetSuiteLabel function. NewIconSuite allocates the memory for the icon suite handle. To release the memory occupied by an icon suite, you must use the DisposeIconSuite function.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

OverrideIconRefFromResource

Replaces the bitmaps in an IconRef with bitmaps from a specified resource file. (Deprecated in Mac OS X v10.5. Use OverrideIconRef instead.)

OSErr OverrideIconRefFromResource (
   IconRef theIconRef,
   const FSSpec *resourceFile,
   SInt16 resourceID
);

Parameters
theIconRef

An IconRef to be updated.

resourceFile

A pointer to the file system specification structure for the resource file containing the replacement bitmaps.

resourceID

The resource ID containing the replacement bitmaps. This value must be non-zero. You should provide a resource of type 'icns' if possible. If an 'icns' resource is not available, Icon Services uses standard icon suite resources, such as 'ICN#', instead.

Return Value

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

Availability
Declared In
IconsCore.h

PlotCIcon

Draws a color icon of resource type 'cicn' to which you have a handle. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

void PlotCIcon (
   const Rect *theRect,
   CIconHandle theIcon
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port.

theIcon

A handle to the color icon structure of the color icon to draw. You can obtain a handle to the icon using the GetCIcon function, or GetResource or other Resource Manager functions.

Discussion

The iconMask field of the CIcon structure determines which pixels in the iconPMap field are drawn and which are not. Only pixels with 1s in corresponding positions in the iconMask field are drawn. If the screen depth is 1 or 2 bits per pixel, this function uses the iconBMap field instead of the iconPMap field (unless the rowBytes field of IconBMap contains 0, indicating that there is no bitmap for the icon).

When this function draws the icon, it uses the bounds field of iconPMap as the source rectangle of the image. If the destination rectangle is not the same size as the icon or its mask, the function stretches or shrinks the icon to fit. The icon’s pixels are remapped to the current depth and color table, if necessary. The bounds fields of iconPMap, iconBMap, and iconMask are expected to be equal in size.

Unlike PlotCIconHandle, this function does not allow you to specify any transforms or alignment. This function uses the QuickDraw function CopyMask and doesn’t send any of its drawing commands through QuickDraw bottleneck functions. Therefore, calls to this function are not recorded as pictures.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PlotCIconHandle

Draws an icon of resource type 'cicn' to which you have a handle. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr PlotCIconHandle (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   CIconHandle theCIcon
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port.

align

Specifies how the function should align the icon within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

transform

Specifies how the function should modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use in this parameter.

theCIcon

A handle to the color icon structure of the icon to draw. You can obtain a handle to the icon using the GetCIcon function or GetResource or other Resource Manager functions.

Return Value

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

Discussion

Unlike PlotCIcon, this function doesn’t honor the current foreground and background colors.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PlotIcon

Draws an icon of resource type 'ICON' to which you have a handle. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

void PlotIcon (
   const Rect *theRect,
   Handle theIcon
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port.

theIcon

A handle to the icon to draw. You must have previously obtained this handle using the GetIcon function, or GetResource or other Resource Manager functions.

Discussion

This function does not allow you to specify any transforms or alignment. The PlotIcon function uses the QuickDraw function CopyBits with the srcCopy transfer mode. To plot an icon of resource type 'ICON' with a specified transform and alignment, use the PlotIconHandle function.

If the destination rectangle is not 32 by 32 pixels, the function stretches or shrinks the icon to fit.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PlotIconHandle

Draws an icon of resource type 'ICON' or 'ICN#' to which you have a handle. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr PlotIconHandle (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   Handle theIcon
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port.

align

Specifies how the function should align the icon within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

transform

Specifies how the function should modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use in this parameter.

theIcon

A handle to the icon to draw. You must have previously obtained a handle to the icon using the GetIcon function, or GetResource or other Resource Manager functions.

Return Value

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

Discussion

To plot an icon from an icon suite, you should normally use PlotIconSuite. This function may not draw the icon correctly if you pass it the handle returned in the theIconData parameter of GetIconFromSuite.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PlotIconID

Draws the icon described by an icon family. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr PlotIconID (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   SInt16 theResID
);

Parameters
theRect

A pointer to the rectangle, specified in local coordinates of the current graphics port, in which to draw the icon.

You cannot determine which icon from the family specified by theResID the function will draw. The function determines, from the size of the specified destination rectangle and the current bit depth of the display device, which icon of a given size to draw from an icon family. For example, if the destination rectangle has the coordinates (100,100,116,116) and the display device is set to 4-bit color, the function draws the icon of type 'ics4' if that icon is available in the icon family.

If the width or height of a destination rectangle is greater than or equal to 32, the function uses the 32-by-32 pixel icon with the appropriate bit depth for the display device. If the destination rectangle is less than 32 by 32 pixels and greater than 16 pixels wide or 12 pixels high, PlotIconID uses the 16-by-16 pixel icon with the appropriate bit depth. If the destination rectangle’s height is less than or equal to 12 pixels or its width is less than or equal to 16 pixels, PlotIconID uses the 12-by-16 pixel icon with the appropriate bit depth. (Typically only the Finder and Standard File Package use 12-by-16 pixel icons.)

The destination rectangle must be exactly 32 by 32 pixels, 16 by 16 pixels, or 12 by 16 pixels for the function to draw the icon without stretching it. If the destination rectangle is not one of these standard sizes, the function expands or shrinks the icon to fit.

align

Specifies how the function should align the icon within the rectangle. For example, you can specify that it center the icon within the rectangle or align it at one side or the other. The function moves the icon so that the edges of its mask align with the specified side or direction. See “Icon Alignment Constants” for a description of the values you can use here.

transform

Specifies how the function should modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use here.

theResID

The resource ID of the icon to draw. The icon resource must be of resource type 'ICN#', 'ics#', 'icl4', 'icl8', 'ics4', or 'ics8'. In general, you should specify your icon resources as purgeable.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

Availability
Declared In
Icons.h

PlotIconMethod

Draws an icon obtained with the aid of your icon getter callback function. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr PlotIconMethod (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   IconGetterUPP theMethod,
   void *yourDataPtr
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port.

align

Specifies how to align the icon within the specified rectangle. See “Icon Alignment Constants” for a description of the values you can use here.

transform

Specifies how the function should modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use here.

theMethod

A universal procedure pointer to your icon getter callback function. PlotIconMethod uses your icon getter function to obtain the icon to draw.

PlotIconMethod passes to your icon getter function the type of the icon to draw and the value specified in the yourDataPtr parameter. The PlotIconMethod function examines the current bit depth of the display devices and calls your icon getter function once for each display device that intersects the rectangle specified in the parameter theRect. Your icon getter function should return a handle to the requested icon’s data. Your icon getter function can get the icon data using whatever method is appropriate to your application. For example, your application might maintain its own cache of icons or use its icon getter function to get an icon from the desktop database.

For more information see the IconGetterProcPtr callback.

yourDataPtr

A pointer to data that is passed to your icon getter callback function.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PlotIconRef

Draws an icon using appropriate size and depth data from an IconRef. (Deprecated in Mac OS X v10.5. Use PlotIconRefInContext instead.)

OSErr PlotIconRef (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   IconServicesUsageFlags theIconServicesUsageFlags,
   IconRef theIconRef
);

Parameters
theRect

A pointer to the rectangle where the icon is to be drawn.

align

A value specifying how Icon Services should align the icon within the rectangle.

transform

A value specifying how Icon Services should modify the appearance of the icon.

theIconServicesUsageFlags

Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.

theIconRef

The IconRef for the icon to draw.

Return Value

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

Discussion

This function is similar to the Icon Utilities function PlotIconSuite.

Availability
Declared In
Icons.h

PlotIconSuite

Draws the icon described by an icon suite using the most appropriate icon in the suite for the current bit depth of the display device and the rectangle in which the icon is to be drawn. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

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

Parameters
theRect

A pointer to the rectangle in which to draw the icon.

The function plots a single icon from the icon suite in the current graphics port. You cannot determine which icon from a given suite it will draw; the function bases this decision on the size of the specified destination rectangle and the current bit depth of the display device. For example, if the destination rectangle has the coordinates (100,100,116,116) and the display device is set to 4-bit color, the function draws the icon of type 'ics4' if that icon is available in the icon suite.

If the width or height of a destination rectangle is greater than or equal to 32 pixels, the function uses the 32-by-32 pixel icon with the appropriate bit depth for the display device. If the destination rectangle is less than 32 by 32 pixels and greater than 16 pixels wide or 12 pixels high, the function uses the 16-by-16 pixel icon with the appropriate bit depth. If the destination rectangle’s height is less than or equal to 12 pixels or its width is less than or equal to 16 pixels, the function uses the 12-by-16 pixel icon with the appropriate bit depth. (Typically, only the Finder and Standard File Package use 12-by-16 pixel icons.)

The destination rectangle passed in the theRect parameter must be exactly 32 by 32 pixels, 16 by 16 pixels, or 12 by 16 pixels for the function to draw the icon without stretching it. If the destination rectangle is not one of these standard sizes, the function expands or shrinks the icon to fit.

align

Specifies how the function should align the icon within the rectangle. For example, you can specify that the function center the icon within the rectangle or align it at one side or the other. See “Icon Alignment Constants” for a description of the values you can use here.

transform

Specifies how the function should modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use here.

If you don’t specify a label constant in this parameter, the function displays the icon using the default label for that icon suite. When you create an icon suite using the GetIconSuite function or the NewIconSuite function, these functions set the default label for the suite to none. To set a new default label for an icon suite, use the SetSuiteLabel function.

theIconSuite

A handle to the icon suite from which the function gets the icon to draw. You can get a handle to an icon suite using the GetIconSuite or NewIconSuite functions.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PlotSICNHandle

Draws a small icon of resource type 'SICN' to which you have a handle. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr PlotSICNHandle (
   const Rect *theRect,
   IconAlignmentType align,
   IconTransformType transform,
   Handle theSICN
);

Parameters
theRect

A pointer to the rectangle in which to draw the icon, specified in local coordinates of the current graphics port.

align

Specifies how the function should align the icon within the rectangle. See “Icon Alignment Constants” for a description of the values you can use in this parameter.

transform

Specifies how the function should modify the appearance of the icon. See “Icon Transformation Constants” for a description of the values you can use in this parameter.

theSICN

A handle to the icon to draw. You can obtain a handle to the icon using GetResource or other Resource Manager functions.

Return Value

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

Discussion

Only 'SICN' resources with a single member—or with two members, the second of which is a mask for the first—plot correctly.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PtInIconID

Determines whether a specified point is within an icon. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Boolean PtInIconID (
   Point testPt,
   const Rect *iconRect,
   IconAlignmentType align,
   SInt16 iconID
);

Parameters
testPt

The point to be tested, specified in local coordinates of the current graphics port. A point is considered to be within an icon if the point is within the icon’s mask.

iconRect

A pointer to the rectangle in which the icon appears, specified in local coordinates of the current graphics port. The function determines, from the size of the rectangle specified in this parameter, which icon mask from the given icon family to test the point against. The rectangle which you specify here should be the same rectangle that you last used to draw the icon. The function then uses the location of this rectangle (and the alignment of the icon in the rectangle) to determine whether the specified point is within the icon.

align

Specifies how the icon against which to hit-test is aligned within the rectangle specified by the iconRect parameter. The alignment which you specify here 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.

iconID

A resource ID for an icon family. In general, you should specify your icon resources as purgeable.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PtInIconMethod

Determines whether a specified point is within an icon obtained with the aid of your icon getter callback function. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Boolean PtInIconMethod (
   Point testPt,
   const Rect *iconRect,
   IconAlignmentType align,
   IconGetterUPP theMethod,
   void *yourDataPtr
);

Parameters
testPt

The point to be tested, specified in local coordinates of the current graphics port. A point is considered to be within an icon if the point is within the icon’s mask.

iconRect

A pointer to the rectangle in which the icon appears, specified in local coordinates of the current graphics port. The rectangle which you specify here should be the same rectangle that you last used to draw the icon.

align

Specifies how the icon against which to hit-test is aligned within the rectangle specified by the iconRect parameter. The alignment which you specify here 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.

theMethod

A universal procedure pointer to your icon getter callback function. PtInIconMethod passes to your icon getter function the type of icon your function should retrieve (either 'ICN#' or 'ics#') and also passes the value specified in the yourDataPtr parameter. The PtInIconMethod function examines the size of the specified rectangle and requests the appropriate icon from your icon getter function. Your icon getter function should return a handle to the requested icon’s data. The PtInIconMethod function extracts the mask from the icon data that your icon getter function returns. If your icon getter function returns data that does not correspond to an icon of type 'ICN#' or type 'ics#', PtInIconMethod attempts to generate a mask from the returned data.

Your icon getter function can get the icon’s data using whatever method is appropriate to your application. For example, your application might maintain its own cache of icons (and pass a pointer to it in the yourDataPtr parameter) or use its icon getter function to get an icon from the desktop database.

See the IconGetterProcPtr callback for more information on creating an icon getter function.

yourDataPtr

A pointer to data that is passed to your icon getter function.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

PtInIconRef

Tests whether a specified point falls within an icon’s mask. (Deprecated in Mac OS X v10.5. Use IconRefContainsCGPoint instead.)

Boolean PtInIconRef (
   const Point *testPt,
   const Rect *iconRect,
   IconAlignmentType align,
   IconServicesUsageFlags theIconServicesUsageFlags,
   IconRef theIconRef
);

Parameters
testPt

A pointer to the location, specified in local coordinates of the current graphics port, that Icon Services tests to see whether it falls within the mask of the indicated icon.

iconRect

A pointer to the rectangle defining the area that Icon Services uses to determine which icon is hit-tested. Use the same Rect value as when the icon was last drawn.

align

A value that specifies how the indicated icon is aligned within the rectangle specified in the iconRect parameter. Use the same IconAlignmentType value as when the icon was last drawn. for a description of possible return values, see “Icon Alignment Constants.”

theIconServicesUsageFlags

Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.

theIconRef

The icon to be tested.

Return Value

true if the point specified in the testPt parameter falls within the appropriate icon mask, false otherwise.

Discussion

This function is similar to the Icon Utilities function PtInIconSuite. The function is useful when you want to determine whether a user has clicked on a particular icon, for example.

Icon Services uses the icon’s black-and-white mask for hit-testing, even if you provide a deep mask.

Availability
Declared In
Icons.h

PtInIconSuite

Determines whether a specified point is within an icon. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Boolean PtInIconSuite (
   Point testPt,
   const Rect *iconRect,
   IconAlignmentType align,
   IconSuiteRef theIconSuite
);

Parameters
testPt

The point to be tested, specified in local coordinates of the current graphics port. A point is considered to be within an icon if the point is within the icon’s mask.

iconRect

A pointer to the rectangle in which the icon appears, specified in local coordinates of the current graphics port. The function determines, from the size of the rectangle specified in this parameter, which icon mask ('ICN#' or 'ics#') from the specified icon suite to test the point against. The function then uses the location of this rectangle (and the location of the icon in the rectangle) to determine whether the given point is within the icon. The rectangle which you specify here should be the same rectangle that you last used to draw the icon.

align

Specifies how the icon against which to hit-test is aligned within the rectangle specified by the iconRect parameter. The alignment which you specify here 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.

theIconSuite

A handle to an icon suite.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

ReadIconFile

Copies data from a given file into an icon family. (Deprecated in Mac OS X v10.5. Use ReadIconFromFSRef instead.)

OSErr ReadIconFile (
   const FSSpec *iconFile,
   IconFamilyHandle *iconFamily
);

Parameters
iconFile

A pointer to the file specification structure for the source file for icon data.

iconFamily

A handle to an iconFamily data structure to be used as the target data structure. Icon Services resizes the handle as needed. For more information on the IconFamily data structure, see 'icns'.

Return Value

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

Availability
Declared In
IconsCore.h

RectInIconID

Hit-tests a rectangle against the appropriate icon mask from an icon family for a specified destination rectangle and alignment. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Boolean RectInIconID (
   const Rect *testRect,
   const Rect *iconRect,
   IconAlignmentType align,
   SInt16 iconID
);

Parameters
testRect

A pointer to the rectangle to be tested, specified in local coordinates of the current graphics port.

iconRect

A pointer to the rectangle in which the icon appears, specified in local coordinates of the current graphics port. The rectangle which you specify here should be the same rectangle that you last used to draw the icon. Like the PtInIconID function, this function determines, from the size of the rectangle specified in this parameter, which icon mask from the icon family to test the testRect parameter against.

align

Specifies how the icon against which to hit-test is aligned within the rectangle specified by iconRect. The alignment which you specify here 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.

iconID

A resource ID for an icon family. In general, you should specify your icon resources as purgeable.

Return Value

TRUE if the rectangle intersects the icon and FALSE if it doesn’t.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

RectInIconMethod

Hit-tests a rectangle against an icon obtained by your icon getter callback function for a specified destination rectangle and alignment. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Boolean RectInIconMethod (
   const Rect *testRect,
   const Rect *iconRect,
   IconAlignmentType align,
   IconGetterUPP theMethod,
   void *yourDataPtr
);

Parameters
testRect

A pointer to the rectangle to be tested, specified in local coordinates of the current graphics port.

iconRect

A pointer to the rectangle in which the icon appears, specified in local coordinates of the current graphics port. The rectangle which you specify here should be the same rectangle that you last used to draw the icon.

align

Specifies how the icon against which to hit-test is aligned within the rectangle specified by iconRect. The alignment which you specify here 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.

theMethod

A universal procedure pointer to your icon getter callback function. RectInIconMethod passes to your icon getter function the type of the icon your function should retrieve and the value specified in the yourDataPtr parameter. The RectInIconMethod function examines the size of the rectangle and requests the appropriate icon from your icon getter function—an icon of icon type 'ICN#' or 'ics#'. Your icon getter function should return a handle to the data of the requested icon type. The RectInIconMethod function extracts the mask from the icon data that your icon getter function returns. If your icon getter function returns data that does not correspond to an icon of type 'ICN#' or type 'ics#', RectInIconMethod attempts to generate a mask from the returned data.

Your icon getter function can get the data for the icon and its mask using whatever method is appropriate to your application. For example, your application might maintain its own cache of icons (and pass a pointer to it in the yourDataPtr parameter) or use its icon getter function to get an icon from the desktop database.

See the IconGetterProcPtr callback for more information on creating an icon getter function.

yourDataPtr

A pointer to data that is passed to your icon getter function.

Return Value

TRUE if the rectangle intersects the icon and FALSE if it doesn’t.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

RectInIconRef

Tests whether a specified rectangle falls within an icon’s mask. (Deprecated in Mac OS X v10.5. Use IconRefIntersectsCGRect instead.)

Boolean RectInIconRef (
   const Rect *testRect,
   const Rect *iconRect,
   IconAlignmentType align,
   IconServicesUsageFlags iconServicesUsageFlags,
   IconRef theIconRef
);

Parameters
testRect

A pointer to the rectangle, specified in local coordinates of the current graphics port, that Icon Services tests to see whether it falls within the mask of the indicated icon.

iconRect

A pointer to the area that Icon Services uses to determine which icon is hit-tested. Use the same Rect value as when the icon was last drawn.

align

A value that specifies how the indicated icon is aligned within the rectangle specified in the iconRect parameter. Use the same IconAlignmentType value as when the icon was last drawn. for a description of possible return values, see “Icon Alignment Constants.”

iconServicesUsageFlags

Reserved for future use. Pass the kIconServicesNormalUsageFlag constant in this parameter.

theIconRef

A pointer to a value of type IconRef specifying the icon family to use for drawing the requested icon.

Return Value

true if the rectangle specified in the testRect parameter intersects the appropriate icon mask, false otherwise.

Discussion

This function is similar to the Icon Utilities function RectInIconSuite. The function is useful when you want to determine whether a user selection intersects a particular icon, for example.

Icon Services uses the icon’s black-and-white mask for hit-testing, even if you provide a deep mask.

Availability
Declared In
Icons.h

RectInIconSuite

Hit-tests a rectangle against the appropriate icon mask from an icon suite for a specified destination rectangle and alignment. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

Boolean RectInIconSuite (
   const Rect *testRect,
   const Rect *iconRect,
   IconAlignmentType align,
   IconSuiteRef theIconSuite
);

Parameters
testRect

A pointer to the rectangle to be tested, specified in local coordinates of the current graphics port.

iconRect

A pointer to the rectangle in which the icon appears, specified in local coordinates of the current graphics port. The rectangle which you specify here should be the same rectangle that you last used to draw the icon. Like the PtInIconSuite function, this function determines, from the size of the rectangle specified in this parameter, which icon mask from the icon suite specified by theIconSuite to test the test rectangle against. For example, if the coordinates of the iconRect parameter are (100,100,116,116) and the icon cache contains entries for each icon family member, RectInIconSuite uses the icon mask defined by the 'ics#' entry.

The function then intersects the rectangle specified by testRect with the icon mask in the iconRect rectangle.

align

Specifies how the icon against which to hit-test is aligned within the rectangle specified by iconRect. The alignment which you specify here 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.

theIconSuite

A handle to an icon suite.

Return Value

TRUE if the rectangle intersects the icon and FALSE if it doesn’t.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

RegisterIconRefFromIconFile

Adds a file-derived IconRef to the Icon Services registry. (Deprecated in Mac OS X v10.5. Use RegisterIconRefFromFSRef instead.)

OSErr RegisterIconRefFromIconFile (
   OSType creator,
   OSType iconType,
   const FSSpec *iconFile,
   IconRef *theIconRef
);

Parameters
creator

The creator code of the icon data you wish to register. 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 icon data you wish to register.

iconFile

A pointer to the file system specification structure for the file to use as the icon data source.

theIconRef

On return, a pointer to the desired icon data.

Return Value

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

Availability
Declared In
IconsCore.h

RegisterIconRefFromResource

Adds a resource-derived IconRef to the Icon Services registry. (Deprecated in Mac OS X v10.5. Use RegisterIconRefFromFSRef instead.)

OSErr RegisterIconRefFromResource (
   OSType creator,
   OSType iconType,
   const FSSpec *resourceFile,
   SInt16 resourceID,
   IconRef *theIconRef
);

Parameters
creator

The creator code of the icon data you wish to register. 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 icon data you wish to register.

resourceFile

A pointer to the file system specification structure for the resource file from which to read the icon data.

resourceID

The resource ID of the icon data to be registered. This value must be non-zero.

You should provide a resource of type 'icns' if possible. If an 'icns' resource is not available, Icon Services uses standard icon suite resources, such as 'ICN#', instead.

theIconRef

On return, a pointer to the desired icon data.

Return Value

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

Discussion

You can use the RegisterIconRefFromResource function to register icons from 'icns' resources or “classic” custom icon resources ( 'ics#' , 'ICN#' , etc.). Icon Services searches 'icns' resources before searching other icon resources.

Calling this function increments the reference count of the IconRef.

Remember to call the function ReleaseIconRef when you're done with an IconRef.

Special Considerations

Before using the recommended replacement function, you need to move the contents of the icon resource into an icon family .icns file.

Availability
Declared In
IconsCore.h

SetIconCacheData

Sets the data associated with an icon cache. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr SetIconCacheData (
   IconCacheRef theCache,
   void *theData
);

Parameters
theCache

A reference to the icon cache whose data is to be set.

theData

A pointer to the data to set.

Return Value

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

Discussion

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

SetIconCacheProc

Sets the icon getter callback function associated with an icon cache. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr SetIconCacheProc (
   IconCacheRef theCache,
   IconGetterUPP theProc
);

Parameters
theCache

A reference to the icon cache whose icon getter function is to be set.

theProc

A universal procedure pointer to the icon getter callback function to associate with the specified cache. See the IconGetterProcPtr callback for more information on icon getter functions.

Return Value

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

Discussion

All the Icon Utilities functions that accept a handle to an icon suite also accept a handle to an icon cache. An icon cache is like an icon suite except that it also contains a pointer to an icon getter callback function and a pointer to data that can be used as a reference constant. An icon cache typically does not contain handles to the icon resources for all icon family members. Instead, if the icon cache does not contain an entry for a specific type of icon in an icon family, the Icon Utilities functions call your application’s icon getter function to retrieve the data for that icon type.

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

SetSuiteLabel

Specifies the default label associated with an icon suite. (Deprecated in Mac OS X v10.5. Use Icon Services instead.)

OSErr SetSuiteLabel (
   IconSuiteRef theSuite,
   SInt16 theLabel
);

Parameters
theSuite

A handle to an icon suite.

theLabel

An integer from 1 to 7 that specifies a label for the icon suite, or 0 to set the icon suite’s label to none. The default label setting helps to determine which of the label colors shown in the Finder’s Label menu is applied to icons of that suite when your application displays them.

You can override the default label setting for a suite by specifying a label in the transform parameter of the PlotIconSuite function. For example, suppose the color currently set for the third label displayed in the Finder’s Label menu is red, and the color for the fourth label is green. If you set the default label for a suite using SetSuiteLabel(theSuite,3), then draw an icon from the same suite using PlotIconSuite and specifying kTransformNone in the transform parameter, the label color red is applied to the icon. However, if you specify kTransformLabel4 in the transform parameter of the PlotIconSuite function, the label color green is applied to the icon.

Return Value

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

Special Considerations

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

Availability
Declared In
Icons.h

WriteIconFile

Copies data from a given icon family into a file. (Deprecated in Mac OS X v10.5. Use the File Manager instead.)

OSErr WriteIconFile (
   IconFamilyHandle iconFamily,
   const FSSpec *iconFile
);

Parameters
iconFamily

A handle to an iconFamily data structure to be used as a source for icon data. For more information on the IconFamily data structure, see 'icns'.

iconFile

A pointer to the file specification structure for the file to use as the target for icon data.

Return Value

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

Special Considerations

Icon Services is designed to read icon data from a file and cache the data, but not to write out icon data. You can use File Manager functions to write your icon data to a file.

Availability
Declared In
IconsCore.h

< Previous PageNext Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-04-06)

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.