Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Using the Icon Utilities

Drawing Icons That Are Not Part of an Icon Family

To draw icons of resource type 'ICON' or 'cicn' in menus and dialog boxes, you can use the Menu Manager and Dialog Manager as described in Inside Macintosh: Macintosh Toolbox Essentials. You can also use Menu Manager routines to draw resources of type 'SICN'.

To draw resources of resource type 'ICON', 'cicn', or 'SICN' in your application's windows, you can use these routines:

Resource type	Routines
'ICON'	PlotIconHandle PlotIcon
'cicn'	PlotCIconHandle PlotCIcon
'SICN'	PlotSICNHandle

The routines in this list that end in Handle allow you to specify alignment and transforms for the icons. You are responsible for disposing of the handle you pass to any of these routines.

Note

Unlike PlotCIcon, PlotCIconHandle doesn't honor the current foreground and background colors.

The listings that follow provide examples of how to draw each of the three icon resource types that are not part of an icon family.

Listing 5-5 shows how to use PlotIcon to draw an icon of resource type 'ICON' without specifying alignment or transforms. The application-defined procedure MyPlotAnICON uses GetIcon to get a handle to the data for the desired icon and then passes the destination rectangle and the handle to PlotIcon.

Listing 5-5 Drawing an icon of resource type 'ICON'

PROCEDURE MyPlotAnICON (resID: Integer; destRect: Rect; 
                        VAR myIcon: Handle);
BEGIN
   myIcon := GetIcon(resID);
   PlotIcon(destRect, myIcon);
END; 

IMPORTANT

When you are finished using a handle obtained from GetIcon, use the ReleaseResource procedure to release the memory occupied by the icon resource data; for more information about ReleaseResource, see the chapter "Resource Manager" in this book.

Listing 5-6 shows how to use PlotIconHandle to draw an icon of resource type 'ICON' with a specific alignment and transform. The application-defined procedure MyPlotAnICONWithAlignAndTransform uses GetIcon to get a handle to the data for the desired icon and then passes the destination rectangle, alignment, transform, and handle to PlotIconHandle.

Listing 5-6 Drawing an icon of resource type 'ICON' with a specific alignment and transform

PROCEDURE MyPlotAnICONWithAlignAndTransform 
              (resID: Integer; destRect: Rect; 
               align: IconAlignmentType; 
               transform: IconTransformType; VAR myIcon: Handle);
VAR 
   myErr: OSErr;
BEGIN
   myIcon := GetIcon(resID);
   myErr := PlotIconHandle(destRect, align, transform, myIcon);
END;

For the PlotIconHandle function in Listing 5-6 to draw the icon without
stretching it, the destination rectangle passed in the destRect parameter of MyPlotAnICONWithAlignAndTransform must be exactly 32 by 32 pixels. If the destination rectangle is not 32 by 32 pixels, PlotIconHandle expands or shrinks the icon to fit.

Listing 5-7 shows how to use PlotCIcon to draw an icon of resource type 'cicn' without specifying alignment or transform. The MyPlotAcicn procedure uses GetCIcon to get a handle to the color icon record of the desired icon and then passes the destination rectangle and handle to PlotCIcon.

Listing 5-7 Drawing an icon of resource type 'cicn'

PROCEDURE MyPlotAcicn (resID: Integer; destRect: Rect;
                       VAR myCicnIcon: CIconHandle);
BEGIN
   myCicnIcon := GetCIcon(resID);
   PlotCIcon(destRect, myCicnIcon);
END;

Listing 5-8 shows how to use PlotCIconHandle to draw an icon of resource type 'cicn' with a specific alignment and transform. Listing 5-8 uses GetCIcon to get a handle to the color icon record of the desired icon and then passes the destination rectangle, alignment, transform, and handle to PlotCIconHandle.

Listing 5-8 Drawing an icon of resource type 'cicn' with a specific alignment and transform

PROCEDURE MyPlotAcicnWithAlignAndTransform 
              (resID: Integer; destRect: Rect; 
               align: IconAlignmentType; 
               transform: IconTransformType; 
               VAR myCicnIcon: CIconHandle);
VAR 
   myErr: OSErr;
BEGIN
   myCicnIcon := GetCIcon(resID);
   myErr := PlotCIconHandle(destRect, align, transform,
                            myCicnIcon);
END;

Listing 5-9 shows how to use PlotSICNHandle to draw an icon of resource type 'SICN' with a specific alignment and transform. The application-defined procedure MyPlotAnSICNWithAlignAndTransform uses GetResource to get a handle to the data for the desired icon and then passes the destination rectangle, alignment, transform, and handle to PlotSICNHandle.

Listing 5-9 Drawing an icon of resource type 'SICN' with a specific alignment and transform

PROCEDURE MyPlotAnSICNWithAlignAndTransform 
              (resID: Integer; destRect: Rect; 
               align: IconAlignmentType; 
               transform: IconTransformType; VAR myIcon: Handle);
VAR 
   myErr: OSErr;
BEGIN
   myIcon := GetResource('SICN', resID);
   myErr := PlotSICNHandle(destRect, align, transform, myIcon);
END;

For the PlotSICNHandle function in Listing 5-9 to draw the icon without
stretching it, the destination rectangle passed in the destRect parameter of MyPlotAnSICNWithAlignAndTransform must be exactly 16 by 16 pixels. If the destination rectangle is not this size, PlotSICNHandle expands or shrinks the
icon to fit.