Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 5 - Icon Utilities / Icon Utilities Reference

Icon Utilities Routines / Creating an Icon Suite

GetIconSuite

You can use the GetIconSuite function to create an icon suite in memory that contains handles to a specified icon family's resources and to return a handle to the icon suite.

FUNCTION GetIconSuite (VAR theIconSuite: Handle;
                       theResID: Integer;
                       selector: IconSelectorValue): OSErr;

theIconSuite

GetIconSuite allocates the memory for and returns, in this parameter, a handle to an icon suite for the requested icon family. To release the memory occupied by an icon suite, you must use the DisposeIconSuite function.

theResID

The resource ID of the icons in the icon family to be read into memory.

selector

A value that indicates which icons from the icon family to include in the icon suite. See the description that follows for a list of constants you can use in this parameter.

DESCRIPTION

The GetIconSuite function returns a handle to a suite of icons for the icon family whose resource ID is specified in the theResID parameter. Use one or more of these constants in the selector parameter to specify which members of the family to include in the icon suite:

CONST 
   svLarge1Bit       = $00000001; {'ICN#' resource} 
   svLarge4Bit       = $00000002; {'icl4' resource} 
   svLarge8Bit       = $00000004; {'icl8' resource} 
   svSmall1Bit       = $00000100; {'ics#' resource} 
   svSmall4Bit       = $00000200; {'ics4' resource} 
   svSmall8Bit       = $00000400; {'ics8' resource} 
   svMini1Bit        = $00010000; {'icm#' resource} 
   svMini4Bit        = $00020000; {'icm4' resource} 
   svMini8Bit        = $00040000; {'icm8' resource} 
   svAllLargeData    = $000000FF; {'ICN#', 'icl4', and 'icl8' }
                                  { resources} 
   svAllSmallData    = $0000FF00; {'ics#', 'ics4', and 'ics8' }
                                  { resources} 
   svAllMiniData     = $00FF0000; {'icm#', 'icm4', and 'icm8' }
                                  { resources} 
   svAll1BitData     = (svLarge1Bit + svSmall1Bit + svMini1Bit); 
   svAll4BitData     = (svLarge4Bit + svSmall4Bit + svMini4Bit); 
   svAll8BitData     = (svLarge8Bit + svSmall8Bit + svMini8Bit); 
   svAllAvailableData= $FFFFFFFF; {all resources of given ID} 

These constants are additive; that is, you can add several constants to include the corresponding family members in the icon suite.

When you create an icon suite using GetIconSuite, it sets the default label for the suite to none. To set a new default label for an icon suite, use the SetSuiteLabel function.

If you call SetResLoad with the load parameter set to FALSE before you call GetIconSuite, the suite is filled with unloaded resource handles.

To perform operations on one or more icons in an icon suite, use the ForEachIconDo function.

To draw the icon described by the icon suite using the icon family member that is most suitable for the current bit depth of the display device, use the PlotIconSuite function.

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough memory in heap zone

SEE ALSO

For examples of the use of the GetIconSuite function, see Listing 5-2 and Listing 5-3 on page 5-11 and page 5-12, respectively.

For a description of the PlotIconSuite and ForEachIconDo functions, see page 5-35 and page 5-38, respectively. For information on the DisposeIconSuite function, see page 5-42.