icon suites
Drawing Icons with System 7 How to use built in utilties for drawing icons
System 7 includes a group of icon drawing utilities used by the Finder. These
utilities have been made available for the use of applications as well. These
routines use a new type of icon resource called an icon family.
An icon family (or suite or an cache) is not actually a single resource but a collection of different icon resources. Each icon resource in a family will
have the same resource ID and a resource type which indicates its size and bit
depth. Icon families remove the need to determine explicity which size or
depth of icon to use in a certain situation. Several system routines take a
handle to an icon family, so that the icon with the proper size and bit depth can
be used when needed. An icon family can contain an icon for every size and bit
depth available or it can contain fewer icons. If the proper icon is not
available, the routines that use icon families will pick the icon that will
produce the best results. Currently Apple has defined three sizes of icons and
three different bit depths for each size. The sizes are large (32 x 32 pixels),
small (16 x 16 pixels ) and mini (12 x 12 pixels). The actual resource
types are defined as follows:
Large1BitMask 'ICN#'
Large4BitData 'icl4'
Large8BitData 'icl8'
Small1BitMask 'ics#'
Small4BitData 'ics4'
Small8BitData 'ics8'
Mini1BitMask 'sicn'
Mini4BitData 'icm4'
Mini8BitData 'icm8'
The 1-bit-per-pixel member of each size also contains the mask data for all
icons of that size (yes, this means that all your icons of a certain size must
have the same mask, regardless of bit depth).
An icon cache is an icon family that also contains a ProcPtr and a refCon. Icon caches are usually sparsely populated. The idea is that if the proper icon
is not available in the family, then a user- defined routine ( referenced by the
ProcPtr) will be called to return the correct icon to draw. The ProcPtr has the following format:
This function should return either the icon data to be used to draw or nil to
signify that this entry in the icon cache does not exist. Icon caches can be used
with all icon family calls, and have a few calls in addition used to manipulate
them.
Drawing Modes or Transforms
In addition to being drawn in various sizes and bit depths, icons can be drawn
with different "modes" or transforms. Transforms are analogous to certain
Finder states for the icons. For example, the transform that you would use to
show an icon of a disk that has been ejected is ttOffline. Here is a list of the
current transforms that are available:
Icon Transform Type values
ttNone
ttDisabled
ttOffline
ttOpen
ttSelected
ttSelectedDisabled
ttSelectedOffline
The actual appearance of the icon drawn by each transform type may vary
with future system software, so you should always try to use the transform
that best fits the state that it represents in your application. In this way you
will remain consistent with any possible future changes to the look and feel of
regular system icons. Note that the ttSelected transform can be added to any of
the other transform types. Additional transform types exist for displaying the
icon of a file inside your application that use the Finder label color to color the
icon. To determine the proper label for a file's icon, you can check bits 1-3
of the fdFlags field of the file's Finder info. These bits contain a number from 0
to 7. Simply add the corresponding ttLabel value to the transform that give the
call. The label values are defined like this:
ttLabel0
ttLabel1
ttLabel2
ttLabel3
ttLabel4
ttLabel5
ttLabel6
ttLabel7
Alignment
Most to icons do not fully fill their rectangle, and it is sometimes necessary to
draw an icon relative to other data (like menu text). In these instances it
would be nice to be able to have the icon move in its rectangle so that it will be
at a predictable location in the destination rectangle. Therefore, when drawing
an icon you can pass one of these standard alignments in the alignment
parameter or you can add a vertical alignment to a horizontal alignment to
create a composite alignment value.
atNone
atVerticalCenter
atTop
atBottom
atHorizontalCenter
atLeft
atRight
There are two types of routines for working with icon families. One type
takes a handle to the icon family. In order to obtain the handle, you must use
one of the routines that creates an icon family such as NewIconSuite, resource ID instead of a handle, and uses the icon family with that resource ID.