Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Icon Services Tasks
This chapter outlines basic and advanced tasks that you can perform using Icon Services.
Basic Tasks With Icon Services
This section describes basic tasks you can perform with Icon Services.
Obtaining and Releasing IconRefs
In order to call Icon Services functions, your application must obtain an IconRef
for the icon data you want to use. There are three functions you can use to accomplish this task; the one you choose depends on how much information you have about the icon you wish to use. If you need an icon from the desktop database or a registered icon (an icon that has been previously identified to Icon Services), the simplest and fastest way to obtain an IconRef
is to use the function GetIconRef
. Icon Services defines a number of constants for non-fileFinder icons, which makes it simple to use the GetIconRef
function to obtain an IconRef
for one of these icons. Listing 3-1 shows an example of how to obtain an IconRef
for the standard Help icon:
Listing 2-1 Obtaining an IconRef for the standard help icon
err = GetIconRef(kOnSystemDisk, kSystemIconsCreator, kHelpIcon, &iconRef); |
If you need an IconRef
for a folder that you know has no custom icons associated with it, use the function GetIconRefFromFolder
. If you need an IconRef
for a file object for which you don’t have any information, use the function GetIconRefFromFile
.
Using IconRefs
Once you obtain a valid IconRef
, you can use Icon Services functions to accomplish two major types of tasks. The first type of task is to draw an icon of the appropriate size and type in a specified area. The second task is checking to see whether the user has clicked on or selected an icon (also known as hit-testing). These functions are designed to be similar to familiar Icon Utilities functions.
Drawing Icons
Icon Services provides two basic drawing functions. For the task of drawing an icon directly to the screen, use the function PlotIconRef
. If you need to convert icon data into a QuickDraw region, use the function IconRefToRgn
.
Hit-Testing
Icon Services provides several ways to determine whether a user has interacted with an icon. To determine whether a user has clicked on an icon, use the function PtInIconRef
. If you need to determine whether an icon falls with a given rectangle (like a selection rectangle, for example), use the function RectInIconRef
. You can also use the function
IconRefToRgn
to do hit-testing.
Advanced Tasks With Icon Services
Icon Services gives you several ways to modify the icon data used by Icon Services. You can add icon data to the Icon Services cache by registering icon data with the functions RegisterIconRefFromIconFamily
or RegisterIconRefFromIconFile
. You can also release registered data by using the function UnregisterIconRef
. You can override existing data in an IconRef
and replace it with custom data by using the functions OverrideIconRef
or OverrideIconRefFromResource
. You can also restore the original data in an IconRef
by using the function RemoveIconOverride
.
Registering Icon Data
You can speed up access to frequently-used icon data by registering icons. The preferred way of registering icons is to use the function RegisterIconRefFromIconFile
. This will make the icon data purgeable if you need to free up memory later. If you can’t use the RegisterIconRefFromResource
function, you can use the function RegisterIconRefFromIconFamily
. To unregister icon data, use the function UnregisterIconRef
.
Updating IconRefs
If you need to refresh icon data without releasing an IconRef
, you can use the function UpdateIconRef
to obtain current icon data. This might be useful after you have changed a file’s custom icon, for example.
Overriding and Restoring Icon Data
You may wish to redraw icons on a temporary basis without going to the trouble of obtaining a new IconRef
. One example of this is when a user has started to download a file and you want to use partial file icons to represent the various stages of the download process. Icon Services provides two functions to temporarily override the data in an IconRef
; the one you choose depends on the source of the data you will use for the override. If you obtain the source data from another IconRef
, use the function OverrideIconRef
. If the source data is contained in a resource, use the function OverrideIconRefFromResource
. You can restore the original icon data by using the function RemoveIconOverride
.
Modifying Reference Counts
You may find it useful to modify the reference count of an IconRef
in preference to obtaining multiple IconRefs
to the same data. This might be useful when your application maintains multiple instances of the same icon data, such as multiple file-copying operations. Use the function AcquireIconRef
to increment the reference count for an IconRef
. This allows you to keep the icon data in the cache without going through the trouble of obtaining additional IconRefs
. If you modify the reference count directly, be sure to decrement the reference count as needed by using the function ReleaseIconRef
.
Flushing IconRefs
When you want to free up memory by releasing purgeable icon data from the cache, the preferred method is to use the function FlushIconRefs
. You may also use the function FlushIconRefsByVolume
, but this has two potential problems:
The additional scope of the
FlushIconRefsByVolume
function means it will take longer to complete.Using the the
FlushIconRefsByVolume
function makes the icon data of all currently usedIconRefs
non-purgeable. This means any subsequent efforts to flush icon data will be much less effective.
Using Badges
A badge is an overlay or replacement for an icon. You can use a badge to signify that a folder contains special files, for example. Badges are described by a 'badg'
resource you store in a file’s resource fork or a folder’s invisible icon file. Figure 3-1 shows a folder alias icon displayed in standard form and with a badge.
There are two steps required to use a custom badge with a file object.
Clear the
kExtendedFlagsAreInvalid
bit and set thekExtendedFlagHasCustomBadge
bit in theextendedFinderFlags
field of theExtendedFileInfo
structure (if the object is a file) or theExtendedFolderInfo
structure (if the object is a folder).Add a resource of type
kCustomBadgeResourceType
('badg'
) and IDkCustomBadgeResourceID
to a file’s resource fork or a folder’s icon file.
There are three ways to use the data from a 'badg'
resource.
The
customBadgeType
andcustomBadgeCreator
fields let you designate a custom badge to display on top of another icon, as shown in Figure 3-1.The
windowBadgeType
andwindowBadgeCreator
fields let you designate which icon to display in Finder window header of the badged file or folder.The
overrideType
andoverrideCreator
fields let you designate the badge as a replacement for the standard icon for this file or folder.
The type and creator codes specified in a'badg'
resource must be registered with Icon Services before you can use the badge. For more information, see Registering Icon Data.
If you supply a custom icon resource for a badge, Icon Services will use it in preference to other available data. For a complete description of the badge resource, see 'badg'
.
Guidelines for Designing Icons
Here are some guidelines to follow if you choose to design custom icons for use with Icon Services.
You must provide at least one of the following icon types:
'ICN#'
,'ics#'
, or'icl#'
.If you provide a deep mask, all of the non-transparent pixels in the deep mask should correspond to a black pixel in the black-and-white mask. This is important for hit-testing and proper erasing and drawing of the icon.
If you provide 32-bit icon data, you should also provide an 8-bit version of the icon. This ensures that the icon can be displayed on an 8-bit display without unwanted dithering.
8-bit icon data is no longer limited to the 34 colors of the classic icon color palette. All 256 colors from the System palette are available.
4-bit icons are still supported. However, the 4-bit display configuration is rarely used and often unsupported, so we recommend that you do not provide 4-bit icon data. If you don’t provide 4-bit icon data, Icon Services will use black-and-white icon data instead.
Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-02-01