Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 7 - Pictures / Pictures Reference

QuickDraw and Picture Utilities Routines / Collecting Picture Information

NewPictInfo

You can survey multiple pictures for such information as colors, picture comments, and fonts, and you can survey multiple pixel maps and bitmaps for color information. Use the NewPictInfo function to begin collecting pictures, pixel maps, and bitmaps for your survey.

FUNCTION NewPictInfo (VAR thePictInfoID: PictInfoID; 
                     verb: Integer; colorsRequested: Integer; 
                     colorPickMethod: Integer; 
                     version: Integer): OSErr;

thePictInfoID

A unique value that denotes your collection of pictures, pixel maps, or bitmaps.

verb

A value indicating what type of information you want the RetrievePictInfo function (described on page 7-57) to return in a PictInfo record (described on page 7-31). When collecting information about pictures, you can use any or all of the following constants or the sum of the integers they represent:

            CONST
            returnColorTable  = 1;  {return a ColorTable record}
            returnPalette     = 2;  {return a Palette record}
            recordComments    = 4;  {return comment information}
            recordFontInfo    = 8;  {return font information}
            suppressBlackAndWhite
                              = 16; {don't include black and }
                                    { white with returned colors}

The constants recordComments and recordFontInfo and the values they represent have no effect when gathering information about the pixel maps and bitmaps included in your survey.

Because the Palette Manager adds black and white when creating a palette, you can specify the number of colors you want minus 2 in the colorsRequested parameter and specify the constant suppressBlackAndWhite in the verb parameter when gathering colors destined for a Palette record or a screen.

colorsRequested

From 1 to 256, the number of colors you want included in the ColorTable or Palette record returned by the RetrievePictInfo function via a PictInfo record.

colorPickMethod

The method by which colors are selected for the ColorTable or Palette record included in the PictInfo record returned by the RetrievePictInfo function. You can use one of the following constants or the integer it represents:

            CONST
            systemMethod   = 0;  {let Picture Utilities choose }
                                 { the method (currently they } 
                                 { always choose popularMethod)}
            popularMethod  = 1;  {return most frequently used }
                                 { colors}
            medianMethod   = 2;  {return a weighted distribution }
                                 { of colors}

You can also create your own color-picking method in a resource file of type 'cpmt' and pass its resource ID in the colorPickMethod parameter. The resource ID must be greater than 127.

version

Always set this parameter to 0.

DESCRIPTION

In the thePictInfoID parameter, the NewPictInfo function returns a unique ID number for use when surveying multiple pictures, pixel maps, and bitmaps for information.

To add the information for a picture to your survey, use the RecordPictInfo function, which is described next. To add the information for a pixel map or a bitmap to your survey, use the RecordPixMapInfo function, which is described on page 7-56. For each of these functions, you identify the survey with the ID number returned by NewPictInfo.

Use the RetrievePictInfo function (described on page 7-57) to return information about the pictures, pixel maps, and bitmaps in the survey. Again, you identify the survey with the ID number returned by NewPictInfo. The RetrievePictInfo function returns your requested information in a PictInfo record.

Use the verb parameter for NewPictInfo to specify whether you want to gather comment or font information for the pictures in the survey. If you want to gather color information, use the verb parameter for NewPictInfo to specify whether you want this information in a ColorTable record, a Palette record, or both. The PictInfo record returned by the RetrievePictInfo function will then include a handle to a ColorTable record or a Palette record, or handles to both. If you want color information, be sure to use the colorPickMethod parameter to specify the method by which to select colors.

The Picture Utilities provide two color-picking methods: one (specified by the popularMethod constant) that gives you the most frequently used colors and one (specified by the medianMethod constant) that gives you the widest range of colors. If you specify the systemMethod constant, the Picture Utilities choose the method; currently they always choose popularMethod. You can also supply a color-picking method of your own.

SPECIAL CONSIDERATIONS

The NewPictInfo function may move or purge memory.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the NewPictInfo function are

Trap macro	Selector
_Pack15	$0602

RESULT CODES

pictInfoVersionErr	-11000	Version number not 0
pictInfoVerbErr	-11002	Invalid verb combination specified
cantLoadPickMethodErr	-11003	Custom pick method not in resource chain
colorsRequestedErr	-11004	Number out of range or greater than that passed to NewPictInfo

SEE ALSO

The PictInfo record is described on page 7-31, the CommentSpec record is described on page 7-29, and the FontSpec record is described on page 7-29. The ColorTable record is described in the chapter "Color QuickDraw" in this book; the Palette record is described in Advanced Color Imaging on the Mac OS. See "Application-Defined Routines" beginning on page 7-60 for more information about creating your own color-picking method for the colorPickMethod parameter.