Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Icon Utilities Reference

Icon Utilities Routines / Drawing Icons From an Icon Suite

PlotIconSuite

You can use the PlotIconSuite function to draw 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.

FUNCTION PlotIconSuite (theRect: Rect; 
                        align: IconAlignmentType;
                        transform: IconTransformType;
                        theIconSuite: Handle): OSErr;

theRect

The rectangle in which to draw the icon. The PlotIconSuite function uses the size of the specified destination rectangle and the current bit depth of the display device to determine which icon from an icon suite to draw.

align

A value that specifies how PlotIconSuite should align the icon within the rectangle. For example, you can specify that PlotIconSuite
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 PlotIconSuite should modify the appearance of the icon. See the description that follows for a list of constants you can use in this parameter.

theIconSuite

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

DESCRIPTION

The PlotIconSuite function plots a single icon from an icon suite in the current graphics port. You cannot determine which icon from a given suite it will draw; PlotIconSuite 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 PlotIconSuite 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, PlotIconSuite 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, PlotIconSuite 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, PlotIconSuite 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 parameter theRect:

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 PlotIconSuite must be exactly 32 by 32 pixels, 16 by 16 pixels, or 12 by 16 pixels for PlotIconSuite to draw the icon without stretching it. If the destination rectangle is not one of these standard sizes, PlotIconSuite expands or shrinks the icon to fit. After stretching or shrinking the icon, the PlotIconSuite 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 PlotIconSuite. 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 icons 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 PlotIconSuite:

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

If you don't specify a label constant in the transform parameter, PlotIconSuite displays the icon using the default label for that icon suite. When you create an icon suite using GetIconSuite or NewIconSuite, 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.

RESULT CODES

noErr	0	No error
noMaskFoundErr	-1000	No mask found

SEE ALSO

For examples of the use of the PlotIconSuite function, see Listing 5-2 and Listing 5-3, starting on page 5-11.

For information on the SetSuiteLabel function, see page 5-40. See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for more information about the file information record.