Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 9 - Desktop Manager / Desktop Manager Reference

Routines / Adding to the Desktop Database

PBDTAddIcon

To add an icon definition to the desktop database, use the PBDTAddIcon function.

FUNCTION PBDTAddIcon (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.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
\xAE	ioResult	OSErr	The result code of the function.
-->	ioDTRefNum	Integer	The desktop database reference number.
-->	ioTagInfo	LongInt	Reserved; must be set to 0.
-->	ioDTBuffer	Ptr	A pointer to the icon's data.
-->	ioDTReqCount	LongInt	The size of the icon's bitmap.
-->	ioIconType	SignedByte	The icon type.
-->	ioFileCreator	OSType	The icon's file creator.
-->	ioFileType	OSType	The icon's file type.

DESCRIPTION

The PBDTAddIcon function adds an icon definition to the desktop database specified in ioDTRefNum. You specify the creator and file type that the icon is associated with in the ioFileCreator and ioFileType fields. For the icon type in ioIconType, specify either a constant or a value from the following list.

Constant	Value	Corresponding resource type	Description
kLargeIcon	1	'ICN#'	Large black-and-white icon with mask
kLarge4BitIcon	2	'icl4'	Large 4-bit color icon
kLarge8BitIcon	3	'icl8'	Large 8-bit color icon
kSmallIcon	4	'ics#'	Small black-and-white icon with mask
kSmall4BitIcon	5	'ics4'	Small 4-bit color icon
kSmall8BitIcon	6	'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. For the number of bytes in ioDTReqCount, you specify either a constant or a value from the following list.

Constant	Value (bytes in bitmap)	Corresponding resource type	Description
kLargeIconSize	256	'ICN#'	Large black-and-white icon with mask
kLarge4BitIconSize	512	'icl4'	Large 4-bit color icon
kLarge8BitIconSize	1024	'icl8'	Large 8-bit color icon
kSmallIconSize	64	'ics#'	Small black-and-white icon with mask
kSmall4BitIconSize	128	'ics4'	Small 4-bit color icon
kSmall8BitIconSize	256	'ics8'	Small 8-bit color icon

You pass a pointer to the icon bitmap in the ioDTBuffer field. You must initialize the ioTagInfo field to 0.

If the database already contains an icon definition for an icon of that type, file type, and file creator, the new definition replaces the old.

RESULT CODES

noErr	0	No error
ioErr	-36	I/O error
wPrErr	-44	Volume is locked through hardware
vLckdErr	-46	Volume is locked through software
rfNumErr	-51	Reference number invalid
extFSErr	-58	External file system--file system identifier is nonzero
afpIconTypeError	-5030	Sizes of new icon and one it replaces don't match