Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Icon Utilities Reference

Icon Utilities Routines / Drawing Icons From Resources

PlotIconID

You can use the PlotIconID function to draw the icon described by an icon family. From the icon family, PlotIconID selects the most appropriate icon resource for the current bit depth of the display device and the rectangle in which the icon is to be drawn.

FUNCTION PlotIconID (theRect: Rect; align: IconAlignmentType;
                     transform: IconTransformType; 
                     theResID: Integer): OSErr;

theRect

The rectangle, specified in local coordinates of the current graphics port, in which to draw the icon. The PlotIconID 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.

align

A value that specifies how PlotIconID should align the icon within the rectangle. For example, you can specify that PlotIconID center the icon within the rectangle or align it at one side or the other. See the description that follows for a list of constants you can use in this parameter.

transform

A value that specifies how PlotIconID should modify the appearance of the icon. See the description that follows for a list of constants you can use in this parameter.

theResID

The resource ID of the icon to draw. The icon resource must be of resource type 'ICN#', 'ics#', 'icl4', 'icl8', 'ics4', or 'ics8'.

DESCRIPTION

The PlotIconID function plots a single icon from the icon family specified by theResID. You cannot determine which icon from the family it will draw; PlotIconID 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 PlotIconID 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, PlotIconID 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.)

You can use these constants in the align parameter to specify the alignment of the icon within the rectangle specified by the theRect parameter:

CONST
   atNone               = $0; {no special alignment}
   atVerticalCenter     = $1; {centered vertically}
   atTop                = $2; {top aligned}
   atBottom             = $3; {bottom aligned}
   atHorizontalCenter   = $4; {centered horizontally}
   atLeft               = $8; {left aligned}
   atRight              = $C; {right aligned}
   atAbsoluteCenter     = (atVerticalCenter + atHorizontalCenter);
   atCenterTop          = (atTop + atHorizontalCenter);
   atCenterBottom       = (atBottom + atHorizontalCenter);
   atCenterLeft         = (atVerticalCenter + atLeft);
   atTopLeft            = (atTop + atLeft);
   atBottomLeft         = (atBottom + atLeft);
   atCenterRight        = (atVerticalCenter + atRight);
   atTopRight           = (atTop + atRight);
   atBottomRight        = (atBottom + atRight);

The destination rectangle passed in the theRect parameter of PlotIconID must be exactly 32 by 32 pixels, 16 by 16 pixels, or 12 by 16 pixels for PlotIconID to draw the icon without stretching it. If the destination rectangle is not one of these standard sizes, PlotIconID expands or shrinks the icon to fit. After stretching or shrinking the icon, the PlotIconID function aligns the icon according to the value specified in the align parameter, moving the icon so that the edges of its mask align with the specified side or direction.

You can pass constants in the transform parameter to specify how you want the icon modified, if at all, when plotted by PlotIconID. If you don't want to specify any transform constants, specify ttNone in the transform parameter.

CONST ttNone         =    $0;

You can use these constants in the transform parameter to transform the icon in a manner analogous to certain Finder states for icons:

CONST
   ttDisabled           = $1;
   ttOffline            = $2;
   ttOpen               = $3;
   ttSelected           = $4000;
   ttSelectedDisabled   = (ttSelected + ttDisabled);
   ttSelectedOffline    = (ttSelected + ttOffline);
   ttSelectedOpen       = (ttSelected + ttOpen);

You can use another group of constants to color the icon using the Finder label colors. To determine the appropriate label for a file's icon, you can check bits 1-3 of the fdFlags field in the file's file information record. These bits contain a number from 0 to 7 indicating the label setting (0 indicates no label). Simply add the corresponding constant from this list to the transform parameter when you call PlotIconID:

CONST
   ttLabel1             = $0100;
   ttLabel2             = $0200;
   ttLabel3             = $0300;
   ttLabel4             = $0400;
   ttLabel5             = $0500;
   ttLabel6             = $0600;
   ttLabel7             = $0700;

RESULT CODES

noErr	0	No error
resNotFound	-192	Resource not found
noMaskFoundErr	-1000	No mask found

SEE ALSO

For an example of the use of the PlotIconID function, see Listing 5-1 on page 5-10.

To restrict the icons from an icon family that are available for use by the Icon Utilities, see "Drawing Specific Icons From an Icon Family" on page 5-12.

For information about the file information record, see the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials.