Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: More Macintosh Toolbox /
Chapter 9 - Desktop Manager / Desktop Manager Reference
Routines / Reading the Desktop Database


PBDTGetIcon

To retrieve an icon definition, use the PBDTGetIcon function.

FUNCTION PBDTGetIcon (paramBlock: DTPBPtr; async: Boolean): OSErr;
paramBlock
A pointer to a desktop parameter block.
async
A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.
--> ioCompletionProcPtrA pointer to a completion routine.
\xAE ioResultOSErrThe result code of the function.
--> ioDTRefNumIntegerThe desktop database reference number.
-->ioTagInfoLongIntReserved; must be set to 0.
--> ioDTBufferPtrA pointer to a buffer to hold the icon's data.
--> ioDTReqCountLongIntThe requested size of the icon's bitmap.
\xAEioDTActCountLongIntThe actual size of the icon's bitmap.
--> ioIconTypeSignedByteThe icon type.
--> ioFileCreatorOSTypeThe icon's file creator.
--> ioFileTypeOSTypeThe icon's file type.

DESCRIPTION
The PBDTGetIcon function returns the bitmap for an icon that represents a file of a given type and creator. (For example, to get the icon for a file of file type 'SFWR' created by the application with a signature of 'WAVE', specify these two values in ioFileType and ioFileCreator.) You pass a pointer to a buffer for the icon bitmap in the ioDTBuffer field. The bitmap is returned in this buffer. You specify the desktop database in ioDTRefNum, the file creator in ioFileCreator, and the file type in ioFileType. For the icon type in ioIconType, specify a constant from the
following list:
ConstantValueCorresponding
resource type
Description
kLargeIcon1'ICN#'Large black-and-white icon
with mask
kLarge4BitIcon2'icl4'Large 4-bit color icon
kLarge8BitIcon3'icl8'Large 8-bit color icon
kSmallIcon4'ics#'Small black-and-white icon
with mask
kSmall4BitIcon5'ics4'Small 4-bit color icon
kSmall8BitIcon6'ics8'Small 8-bit color icon

The value you supply in ioDTReqCount is the size in bytes of the buffer that you've allocated for the icon's bitmap pointed to by ioDTBuffer; this value depends on the icon type. Be sure to allocate enough storage for the icon data; 1024 bytes is the largest amount required for any icon in System 7. You can use constants to indicate the amount of memory you have provided for the icon's data. The following list shows these constants and, for each icon type, shows the amount of bytes you should allocate.
ConstantValue
(bytes)
Corresponding
resource type
Description
kLargeIconSize256'ICN#'Large black-and-white icon
with mask
kLarge4BitIconSize512'icl4'Large 4-bit color icon
kLarge8BitIconSize1024'icl8'Large 8-bit color icon
kSmallIconSize64'ics#'Small black-and-white icon
with mask
kSmall4BitIconSize128'ics4'Small 4-bit color icon
kSmall8BitIconSize256'ics8'Small 8-bit color icon

The value in ioDTActCount reflects the size of the bitmap actually retrieved. If ioDTActCount is larger than ioDTReqCount, only the amount of data allowed
by ioDTReqCount is valid.

RESULT CODES
noErr0No error
ioErr-36I/O error
rfNumErr-51Reference number invalid
extFSErr-58External file system--file system identifier is nonzero
afpItemNotFound-5012Information not found

Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996