TABLE OF CONTENTS icon.library/AddFreeList icon.library/BumpRevision icon.library/BumpRevisionLength icon.library/ChangeToSelectedIconColor icon.library/DeleteDiskObject icon.library/DrawIconStateA icon.library/DupDiskObjectA icon.library/FindToolType icon.library/FreeAlloc icon.library/FreeDiskObject icon.library/FreeFree icon.library/FreeFreeList icon.library/GetDefDiskObject icon.library/GetDiskObject icon.library/GetDiskObjectNew icon.library/GetIconRectangleA icon.library/GetIconTagList icon.library/IconControlA icon.library/LayoutIconA icon.library/MatchToolValue icon.library/NewDiskObject icon.library/PutDefDiskObject icon.library/PutDiskObject icon.library/PutIconTagList icon.library/AddFreeList icon.library/AddFreeList NAME AddFreeList - add memory to a free list. SYNOPSIS BOOL status = AddFreeList(struct FreeList *freelist, APTR mem, uint32 len); FUNCTION This routine adds the specified memory to the free list. The free list will be extended (if required). If there is not enough memory to complete the call, NULL is returned. Note that AddFreeList() does NOT allocate the requested memory. It only records the memory in the free list. INPUTS freelist -- a pointer to a FreeList structure mem -- the base of the memory to be recorded len -- the length of the memory to be recorded RESULTS status -- TRUE if the call succeeded else FALSE; SEE ALSO exec.library/AllocTaskMemEntry exec.library/FreeEntry icon.library/FreeFreeList workbench/workbench.h icon.library/BumpRevision icon.library/BumpRevision NAME BumpRevision - reformat a name for a second copy. SYNOPSIS result = BumpRevision(newbuf, oldname) STRPTR BumpRevision(STRPTR, STRPTR); FUNCTION BumpRevision takes a name and turns it into a "copy_of_name". It knows how to deal with copies of copies. The routine will truncate the new name to the maximum dos name size (currently 30 characters). INPUTS newbuf - the new buffer that will receive the name (it must be at least 31 characters long). oldname - the original name RESULTS result - a pointer to newbuf EXAMPLE oldname newbuf ------- ------ "foo" "Copy_of_foo" "Copy_of_foo" "Copy_2_of_foo" "Copy_2_of_foo" "Copy_3_of_foo" "Copy_199_of_foo" "Copy_200_of_foo" "Copy foo" "Copy_of_copy foo" "Copy_0_of_foo" "Copy_1_of_foo" "012345678901234567890123456789" "Copy_of_0123456789012345678901" NOTES Please use BumpRevisionLength() with a larger buffer with icon.library 51.14 or higher. SEE ALSO icon.library/BumpRevisionLength icon.library/BumpRevisionLength icon.library/BumpRevisionLength NAME BumpRevisionLength - reformat a name for a second copy. (V51.14) SYNOPSIS result = BumpRevisionLength(newbuf, oldname, maxlength) STRPTR BumpRevisionLength(STRPTR, STRPTR, uint32); FUNCTION BumpRevisionLength takes a name and turns it into a "copy_of_name". It knows how to deal with copies of copies. The routine will truncate the new name to the passed in maximum length. INPUTS newbuf - the new buffer that will receive the name (it must be at least maxlength + 1 characters long). oldname - the original name maxlength - the maximum length of the new name. Must be at least 30. RESULTS result - a pointer to newbuf or NULL when maxlength was smaller than 30. EXAMPLE oldname maxlength newbuf ------- --------- ------ "foo" 30 "Copy_of_foo" "Copy_of_foo" 30 "Copy_2_of_foo" "Copy_2_of_foo" 30 "Copy_3_of_foo" "Copy_199_of_foo" 30 "Copy_200_of_foo" "Copy foo" 30 "Copy_of_copy foo" "Copy_0_of_foo" 30 "Copy_1_of_foo" "01234567890123456789012345" 30 "Copy_of_0123456789012345678901" "01234567890123456789012345" 100 "Copy_of_01234567890123456789012345" SEE ALSO icon.library/BumpRevision icon.library/ChangeToSelectedIconColor icon.library/ChangeToSelectedIconColor NAME ChangeToSelectedIconColor -- Modify an RGB colour value for use in a selected icon image (V44) SYNOPSIS ChangeToSelectedIconColor(cr) VOID ChangeToSelectedIconColor(struct ColorRegister *cr); FUNCTION This function will change the provided RGB colour value to make it suitable for use in an icon's select image. This may involve darkening or toning the colour. Usually, icon.library calls this function when creating a select image for palette mapped icons which do not contain "real" select images. INPUTS cr -- Pointer to a ColorRegister, containing the RGB colour value to be changed. icon.library/DeleteDiskObject icon.library/DeleteDiskObject NAME DeleteDiskObject - Delete a Workbench disk object from disk. (V37) SYNOPSIS result = DeleteDiskObject(name) BOOL DeleteDiskObject(STRPTR); FUNCTION This routine will try to delete a Workbench disk object from disk. The name parameter will have ".info" postpended to it, and the icon file of that name will be deleted. If the call fails, it will return FALSE. The reason for the failure may be obtained via dos.library/IoErr(). This call also updates the Workbench screen if needed. Using this routine protects you from any future changes to the way icons are stored within the system. INPUTS name -- name of the object (char *) RESULTS result -- TRUE if it worked, FALSE if not. EXAMPLE error = 0; /* Check if you have the right library version */ if(IconBase->lib_Version > 36) { if (!DeleteDiskObject(name)) error = IoErr(); } else { /* Delete name plus ".info" */ } if (error != 0) { /* Do error routine...*/ } SEE ALSO dos.library/IoErr icon.library/PutDiskObject icon.library/GetDiskObject icon.library/FreeDiskObject icon.library/GetIconTagList icon.library/PutIconTagList icon.library/DrawIconStateA icon.library/DrawIconStateA NAME DrawIconStateA -- Draw an icon as if it were an image (V44) SYNOPSIS DrawIconStateA(rp,icon,label,leftEdge,topEdge,state,tags) VOID DrawIconStateA(struct RastPort *rp,struct DiskObject *icon, STRPTR label,LONG leftEdge,LONG topEdge, ULONG state,struct TagItem *tags); DrawIconState(rp,icon,label,leftEdge,topEdge,state,...); VOID DrawIconState(struct RastPort *rp,struct DiskObject *icon, STRPTR label,LONG leftEdge,LONG topEdge, ULONG state,...); FUNCTION This function will draw an icon as if it were an image; if a label is provided, it will be printed below it. INPUTS rp -- Pointer to the RastPort to draw into; the RastPort clipping rules, font, style, text colours and drawing mode will be used. icon -- Pointer to a struct DiskObject. label -- Pointer to a NUL-terminated string, or NULL if no label text is to be printed. leftEdge, topEdge -- Coordinates at which the icon image should be drawn, including its border; please note that the icon label may extend in whole or in part beyond the leftEdge you have specified. state -- Select how and which icon image should be drawn; see intuition/imageclass.h for supported states. tags -- Additional drawing options TAGS ICONDRAWA_DrawInfo (struct DrawInfo *) -- Drawing information data associated with the RastPort to draw into. The DrawInfo contents affect the colours of the border drawn around the icon image and also carry display aspect ratio information. If this tag is NULL, the default rendering pens for the screen selected via IconControl(...,ICONA_SetGlobalScreen,...) will be used instead. This tag defaults to NULL. ICONDRAWA_Frameless (BOOL) -- Draw the icon without the surrounding border. This tag defaults to FALSE. ICONDRAWA_Borderless (BOOL) -- Draw the icon without the surrounding border and frame. This tag defaults to FALSE. ICONDRAWA_EraseBackground (BOOL) -- When drawing a frameless icon, erase the icon background before drawing the icon. This tag defaults to TRUE. ICONDRAWA_IsLink (BOOL) -- The icon to be drawn refers to a linked object. This property should visualized. By default, this means that the icon label will be drawn underlined. This tag defaults to FALSE. ICONDRAWA_Properties (ULONG) -- Optional properties of the icon to be drawn, combined as flags in a longword. Each property can be visualized by altering the way the icon is drawn. You can pass any combination of the ICON_#? property flags defined in . (V51) This tag defaults to zero (no special properties). ICONDRAWA_DrawIcon (BOOL) -- If FALSE, the actual icon image won't be drawn. Everything else, such as the background or the label (if present), will still be rendered. (V51) This tag defaults to TRUE. ICONDRAWA_EraseLabelBackground (BOOL) -- When the icon label is to be drawn in JAM1 mode, erase the background of the text before drawing it. (V51) This tag defaults to TRUE. ICONDRAWA_Transparency (LONG) -- Override the transparency value in range from 0 (invisible) to 255 (opaque) which would be normally used for drawing the icon image. (V51) This tag defaults to -1, which means that the transparency is not overridden. ICONDRAWA_Width (UWORD) -- Specify a width for the icon to be drawn. The first time a particular width is requested, a scaled version of the icon's imagery is generated and cached, in order to speed up any subsequent redraws. When you no longer need to draw the icon at that size, you can dispose of the cached scaled size via IconControlA(), with ICONCTRLA_RemScaledSize. You can specify either an exact width, or a percentage of the normal icon width with the SIZEPERC() macro defined in ; if you pass -1 (~0UL) for the width, and are also requesting a specific height with ICONDRAWA_Height, the new width will be calculated so that the normal icon's aspect ratio is preserved. See also ICONGETA_Width, which this tag is an alias of. (V51) This tag defaults to zero, which means not to change the original width. ICONDRAWA_Height (UWORD) -- Specify a height for the icon to be drawn. The first time a particular height is requested, a scaled version of the icon's imagery is generated and cached, in order to speed up any subsequent redraws. When you no longer need to draw the icon at that size, you can dispose of the cached scaled size via IconControlA(), with ICONCTRLA_RemScaledSize. You can specify either an exact height, or a percentage of the normal icon height with the SIZEPERC() macro defined in ; if you pass -1 (~0UL) for the height, and are also requesting a specific width with ICONDRAWA_Width, the new height will be calculated so that the normal icon's aspect ratio is preserved. See also ICONGETA_Height, which this tag is an alias of. (V51) This tag defaults to zero, which means not to change the original height. ICONDRAWA_SizeBounds (struct Rectangle *) -- Specify the size limits for the icon to be drawn. It will never be drawn larger than the maximum width and height, nor smaller than the minimum width and height (unless it's already smaller than that at its original size, in which case the original size will also become the minimum size). If the icon's size (either original, or requested via the ICONDRAWA_Width/ICONDRAWA_Height tags) doesn't respect the specified bounds, the icon image will be scaled up or down accordingly; the expected aspect ratio will be preserved whenever possible. (V53) This tag defaults to NULL, which means 8x8 for the minimum width/height and 256x256 for the maximum width/height. The bounds are passed as a Rectangle structure with the minimum sizes in MinX and MinY, and the maximum sizes in MaxX and MaxY. ICONDRAWA_AllowUpscaling (BOOL) -- Tell icon.library to enforce the minimum size specified with ICONDRAWA_SizeBounds even when the icon's original size is already smaller than that. This means the icon image may be made larger even if no upscaling was explicitly requested. By default this doesn't happen as icon images designed for a certain size don't usually look very good if scaled up. (V53) This tag defaults to FALSE. ICONDRAWA_Borders (struct Rectangle *) -- Specify the size of the (possibly invisible) borders around the icon to be drawn, overriding the global icon border sizes set via ICONCTRLA_SetGlobalEmbossRect for this single call of DrawIconStateA(). Pass a pointer to a Rectangle structure, with MinX and MinY (left and top borders) being negative values in the range [-255..-1] and MaxX and MaxY (right and bottom borders) being positive values in the range [1..255]. (V53) This tag defaults to NULL, which means the global border sizes should be used. EXAMPLE /* Draw the icon in its normal state, without * a label but including a frame. */ struct RastPort *rp; struct DiskObject *icon; DrawIconStateA(rp,icon,NULL,0,0,IDS_NORMAL,NULL); /* The same again, but without a frame. */ DrawIconState(rp,icon,NULL,0,0,IDS_NORMAL, ICONDRAWA_Frameless,TRUE, TAG_DONE); /* Draw the icon in selected state with a border; the * frame colours come from the given DrawInfo. */ struct DrawInfo *drawInfo; DrawIconState(rp,icon,NULL,0,0,IDS_SELECTED, ICONDRAWA_DrawInfo,drawInfo, TAG_DONE); SEE ALSO workbench/icon.h workbench/workbench.h intuition/imageclass.h intuition/screens.h intuition.library/DrawImageState icon.library/GetIconRectangleA icon.library/IconControlA icon.library/DupDiskObjectA icon.library/DupDiskObjectA NAME DupDiskObjectA -- Duplicate an icon (V44) SYNOPSIS icon = DupDiskObjectA(icon,tags); struct DiskObject * DupDiskObjectA(struct DiskObject *icon, struct TagItem *tags); icon = DupDiskObject(icon,tag1,...); struct DiskObject * DupDiskObject(struct DiskObject *icon, Tag tag1,...); FUNCTION This function is used to create a duplicate of a DiskObject in memory. It can also be used to create an extended ("native") DiskObject data structure from an existing, traditional format DiskObject data structure. INPUTS icon -- Pointer to the icon to be duplicated. tags -- Control options. TAGS ICONDUPA_DuplicateDrawerData (BOOL) -- Duplicate the DrawerData, if available. This tag defaults to TRUE. ICONDUPA_DuplicateImages (BOOL) -- Duplicate the icon images; note that this DOES NOT include the associated image data. To get the image data duplicated, too, also use the ICONDUPA_DuplicateImageData tag. This tag defaults to TRUE. ICONDUPA_DuplicateImageData (BOOL) -- Duplicate the icon image data; this tag works together with the ICONDUPA_DuplicateImages tag. If ICONDUPA_DuplicateImageData is set to TRUE, you must also set ICONDUPA_DuplicateImages to TRUE. This tag defaults to TRUE. ICONDUPA_DuplicateDefaultTool (BOOL) -- Duplicate the icon default tool, if available. This tag defaults to TRUE. ICONDUPA_DuplicateToolTypes (BOOL) -- Duplicate the icon tool types, if available. This tag defaults to TRUE. ICONDUPA_DuplicateToolWindow (BOOL) -- Duplicate the icon tool window if available. This tag defaults to TRUE. ICONDUPA_DuplicateScaledSizes (BOOL) -- Duplicate any scaled versions of the icon's imagery. (V51) This tag defaults to FALSE. ICONDUPA_Width (UWORD) -- Request a specific width for the icon to be duplicated. If the icon was supplied by an external loader module which supports scaling (e.g. a vector icon loader) the result will be a new icon of the requested width. Otherwise, the requested width will be ignored, unless you also pass ICONDUPA_ForceScaling with a TRUE value, in which case icon.library will perform a manual bitmap rescaling of the icon's imagery in order to satisfy the request. You can request either an exact width, or a percentage of the original width with the SIZEPERC() macro defined in . If you pass -1 (~0UL) for the width, and are also requesting a specific height with ICONDUPA_Height, the width of the duplicate will be calculated so that the original icon's aspect ratio is preserved. (V51) This tag defaults to zero, which means not to change the original width. ICONDUPA_Height (UWORD) -- Request a specific height for the icon to be duplicated. If the icon was supplied by an external loader module which supports scaling (e.g. a vector icon loader) the result will be a new icon of the requested height. Otherwise, the requested height will be ignored, unless you also pass ICONDUPA_ForceScaling with a TRUE value, in which case icon.library will perform a manual bitmap rescaling of the icon's imagery in order to satisfy the request. You can request either an exact height, or a percentage of the original height with the SIZEPERC() macro defined in . If you pass -1 (~0UL) for the height, and are also requesting a specific width with ICONDUPA_Width, the height of the duplicate will be calculated so that the original icon's aspect ratio is preserved. (V51) This tag defaults to zero, which means not to change the original height. ICONDUPA_ForceScaling (BOOL) -- Tell icon.library to perform a manual bitmap rescaling of the duplicate icon if it doesn't already have the size requested with ICONDUPA_Width and ICONDUPA_Height. (V51) This tag defaults to FALSE. ICONDUPA_SizeBounds (struct Rectangle *) -- Specify the size limits for the icon to be duplicated. It will never end up being larger than the maximum width and height, nor smaller than the minimum width and height (unless it's already smaller than that at its original size, in which case the original size will also become the minimum size). If the icon's size (either original, or requested via the ICONDUPA_Width/ICONDUPA_Height tags) doesn't respect the specified bounds, the icon image will be scaled up or down accordingly; the expected aspect ratio will be preserved whenever possible. (V53) This tag defaults to NULL, which means 8x8 for the minimum width/height and 256x256 for the maximum width/height. The bounds are passed as a Rectangle structure with the minimum sizes in MinX and MinY, and the maximum sizes in MaxX and MaxY. ICONDUPA_AllowUpscaling (BOOL) -- Tell icon.library to enforce the minimum size specified with ICONDUPA_SizeBounds even when the icon's original size is already smaller than that. This means the icon image may be made larger even if no upscaling was explicitly requested. By default this doesn't happen as icon images designed for a certain size don't usually look very good if scaled up. (V53) This tag defaults to FALSE. ICONDUPA_ActivateImageData (BOOL) -- If the source icon contains palette mapped image data that was never put to use (this happens if it is retrieved with the GetDiskObject() call rather than the new GetIconTagList() call), this tag will cause the image data to be analyzed and an attempt to be made to use that image data in the duplicate. The resulting icon will be remapped for display on the default screen, such as the Workbench screen unless you use the ICONGETA_Screen tag (see below). NOTE: this tag implies { ICONDUPA_DuplicateImages, TRUE } and { ICONDUPA_DuplicateImageData, TRUE } if set to TRUE. This tag defaults to FALSE. ICONGETA_Screen (struct Screen *) -- If you specified that the palette mapped image data attached to an icon should be activated (via "ICONDUPA_ActivateImageData,TRUE") this tag allows you to choose the screen the icon is to be remapped to. It works just like the corresponding tag for the icon.library/GetIconTagList call. There is no default value for this tag, i.e. if the tag is omitted, the icon will be remapped to the default screen. This tag was introduced in icon.library 44.535. ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to store error codes in. Note that this variable will be initialized regardless of whether an error occured or not. Thus, you can check for an error condition by comparing the variable contents against 0; 0 indicates success, all other values are error codes as defined by dos.library. RESULT icon -- Pointer to a struct DiskObject or NULL in case of error. You can use IoErr() to retrieve the error code or use the ICONA_ErrorCode tag instead. NOTES Any data you chose not to have duplicated will be set to NULL. For example, if you specified "ICONDUPA_DuplicateImages,FALSE", then the resulting icon's do_Gadget.GadgetRender and do_Gadget.SelectRender will both be NULL. BUGS icon.library will try to preserve the original bitmapped image data loaded with a palette mapped icon. If you duplicated this type of icon, the preserved original bitmapped image data would not be transferred to the copy. This was fixed in V44.527. For this feature to work, you must specify that the image data should be duplicated via "ICONDUPA_DuplicateImages,TRUE". SEE ALSO dos.library/IoErr icon.library/GetIconTagList workbench/icon.h workbench/workbench.h icon.library/FindToolType icon.library/FindToolType NAME FindToolType - find the value of a ToolType variable. SYNOPSIS value = FindToolType(toolTypeArray, typeName) STRPTR FindToolType(STRPTR *, STRPTR); FUNCTION This function searches a tool type array for a given entry, and returns a pointer to that entry. This is useful for finding standard tool type variables. The returned value is not a new copy of the string but is only a pointer to the part of the string after typeName. INPUTS toolTypeArray -- an array of strings (STRPTR *). typeName -- the name of the tooltype entry (STRPTR). RESULTS value -- a pointer to a string that is the value bound to typeName, or NULL if typeName is not in the toolTypeArray. EXAMPLE Assume the tool type array has two strings in it: "FILETYPE=text" "TEMPDIR=:t" FindToolType( toolTypeArray, "FILETYPE" ) returns "text" FindToolType( toolTypeArray, "filetype" ) returns "text" FindToolType( toolTypeArray, "TEMPDIR" ) returns ":t" FindToolType( toolTypeArray, "MAXSIZE" ) returns NULL FindToolType( toolTypeArray, "text" ) returns NULL FindToolType( toolTypeArray, ":t" ) returns NULL NOTES icon.library V44 tolerates tool type strings with additional blanks around the '=' character, such as in "FILETYPE = text". Older icon.library versions did not support this. SEE ALSO icon.library/MatchToolValue icon.library/FreeAlloc icon.library/FreeAlloc NAME FreeAlloc - allocate memory and add it to a free list (V36). SYNOPSIS APTR memory = FreeAlloc(struct FreeList *freelist, uint32 len, uint32 type); FUNCTION This routine allocates the amount of memory specified and then adds it to the free list. The free list will be extended (if required). If there is not enough memory to complete the call, a null is returned. Note that FreeAlloc not only allocates the requested memory but also records the memory in the free list. INPUTS freelist -- a pointer to a FreeList structure len -- the length of the memory to be recorded; must be > 0 type -- the type of memory to be allocated RESULTS memory -- a pointer to the newly allocated memory chunk or zero if the call failed. NOTES This function was implemented in all icon.library versions starting with V36. However, it was never documented. SEE ALSO AllocTaskMemEntry, FreeEntry, FreeFreeList, FreeFree icon.library/FreeDiskObject icon.library/FreeDiskObject NAME FreeDiskObject - free all memory in a Workbench disk object. SYNOPSIS FreeDiskObject(diskobj) void FreeDiskObject(struct DiskObject *); FUNCTION This routine frees all memory in a Workbench disk object, and the object itself. It is implemented via FreeFreeList(). GetDiskObject() takes care of all the initialization required to set up the object's free list. This procedure may ONLY be called on a DiskObject allocated via GetDiskObject(). INPUTS diskobj -- a pointer to a DiskObject structure; as of V44, a NULL diskobj pointer will be ignored. SEE ALSO icon.library/GetDiskObject icon.library/PutDiskObject icon.library/DeleteDiskObject icon.library/FreeFreeList icon.library/GetIconTagList icon.library/PutIconTagList icon.library/FreeFree icon.library/FreeFree NAME FreeFree - free memory tracked by a free list (V44). SYNOPSIS BOOL found = FreeFree(struct FreeList *free, APTR memory); FUNCTION This routine is the counterpart to FreeAlloc(). Unlike FreeFreeList(), which releases all the memory allocated in the tracking list, only a single entry is deallocated. INPUTS free -- a pointer to a FreeList structure memory -- pointer to the memory chunk to be deallocated; it is safe to pass NULL or the address of a memory chunk which is not even part of the FreeList RESULTS found -- TRUE if the memory chunk was found in the FreeList and could be released, FALSE otherwise. The result code was introduced in V46; older library implementations will not return any meaningful result NOTES This function was implemented in all icon.library versions starting with V44. However, it was never documented. Deallocating single chunks is an expensive operation owing to the design of the FreeList data structure. It takes time to search for the right list entry to be deallocated, and when the deallocation is performed, an used memory tracking slot will remain that will not be deallocated until FreeFreeList() is called. Calling FreeFreeList() and calling FreeFree() for every memory chunk tracked is not equivalent! As part of the memory tracking process additional memory is allocated for every memory chunk which can be freed only by calling FreeFreeList(). BUGS This function name is not particularly meaningful... SEE ALSO AllocTaskMemEntry, FreeEntry, FreeFreeList, FreeAlloc icon.library/FreeFreeList icon.library/FreeFreeList NAME FreeFreeList - free all memory in a free list. SYNOPSIS void FreeFreeList(struct FreeList *freelist); FUNCTION This routine frees all memory in a free list, and the free list itself. It is useful for easily getting rid of all memory in a series of structures. There is a free list in a Workbench object, and this contains all the memory associated with that object. A FreeList is a list of MemList structures. See the MemList and MemEntry documentation for more information. If the FreeList itself is in the free list, it must be in the first MemList in the FreeList. INPUTS freelist -- a pointer to a FreeList structure; as of V44 a NULL free parameter will be ignored. SEE ALSO exec.library/AllocTaskMemEntry exec.library/FreeEntry icon.library/AddFreeList workbench/workbench.h icon.library/GetDefDiskObject icon.library/GetDefDiskObject NAME GetDefDiskObject - read default wb disk object from disk. (V36) SYNOPSIS diskobj = GetDefDiskObject(def_type) struct DiskObject *GetDefDiskObject(LONG); FUNCTION This routine reads in a default Workbench disk object from disk. The valid def_types can be found in workbench/workbench.h and currently include WBDISK thru WBKICK. If the call fails, it will return NULL. The reason for the failure may be obtained via IoErr(). Using this routine protects you from any future changes to the way default icons are stored within the system. INPUTS def_type -- default icon type (WBDISK thru WBKICK). RESULTS diskobj -- the default Workbench disk object in question NOTES icon.library V36 through V40 did not support the WBDEVICE default icon type. SEE ALSO dos.library/IoErr icon.library/PutDefDiskObject icon.library/PutIconTagList icon.library/GetDiskObject icon.library/GetDiskObject NAME GetDiskObject - read in a Workbench disk object from disk. SYNOPSIS diskobj = GetDiskObject(name) struct DiskObject *GetDiskObject(STRPTR); FUNCTION This routine reads in a Workbench disk object in from disk. The name parameter will have ".info" postpended to it, and the icon file of that name will be read. If the call fails, it will return NULL. The reason for the failure may be obtained via IoErr(). Using this routine protects you from any future changes to the way icons are stored within the system. A FreeList structure is allocated just after the DiskObject structure; FreeDiskObject makes use of this to get rid of the memory that was allocated. INPUTS name -- name of the object (STRPTR) or NULL if you just want a DiskObject structure allocated for you (useful when calling AddAppIcon() in workbench.library). RESULTS diskobj -- the Workbench disk object in question SEE ALSO dos.library/IoErr icon.library/DeleteDiskObject icon.library/FreeDiskObject icon.library/GetDiskObjectNew icon.library/GetIconTagList icon.library/NewDiskObject icon.library/PutDiskObject icon.library/PutIconTagList workbench.library/AddAppIconA icon.library/GetDiskObjectNew icon.library/GetDiskObjectNew NAME GetDiskObjectNew - read in a Workbench disk object from disk. (V36) SYNOPSIS diskobj = GetDiskObjectNew(name) struct DiskObject *GetDiskObjectNew(STRPTR); FUNCTION This routine reads in a Workbench disk object in from disk. The name parameter will have ".info" postpended to it, and the icon file of that name will be read. If the call fails, it will return zero. The reason for the failure may be obtained via IoErr(). Using this routine protects you from any future changes to the way icons are stored within the system. A FreeList structure is allocated just after the DiskObject structure; FreeDiskObject makes use of this to get rid of the memory that was allocated. This call is functionally identical to GetDiskObject() with one exception. If its call to GetDiskObject() fails, this function calls GetDefDiskObject(). This is useful when there is no .info file for the icon you are trying to get a disk object for. Applications that use workbench application windows MUST use this call if they want to handle the user dropping an icon (that doesn't have a ".info" file) on their window. The V2.0 icon editor program is an example of a Workbench application window that uses this call. INPUTS name -- name of the object (STRPTR) or NULL if you just want a DiskObject structure allocated for you (useful when calling AddAppIcon() in workbench.library). RESULTS diskobj -- the Workbench disk object in question SEE ALSO dos.library/IoErr icon.library/FreeDiskObject icon.library/GetDiskObject icon.library/PutDiskObject icon.library/DeleteDiskObject icon.library/GetIconTagList icon.library/PutIconTagList workbench.library/AddAppIconA icon.library/GetIconRectangleA icon.library/GetIconRectangleA NAME GetIconRectangleA -- Query the size of the area an icon renders into (V44) SYNOPSIS success = GetIconRectangleA(rp,icon,label,rectangle,tags) BOOL GetIconRectangleA(struct RastPort *rp,struct DiskObject *icon, STRPTR label,struct Rectangle *rectangle, struct TagItem *tags); success = GetIconRectangle(rp,icon,label,rectangle,...); BOOL GetIconRectangle(struct RastPort *rp,struct DiskObject *icon, STRPTR label,struct Rectangle *rectangle,...); FUNCTION This function will calculate the size of the area icon rendering would affect. INPUTS rp -- Pointer to the RastPort to use for calculating the the size of the label with respect to the font and style options currently in use; this parameter may be NULL if the label is NULL, too. icon -- Pointer to a struct DiskObject. label -- Pointer to a NUL-terminated string, or NULL if no label text is to enter the calculation. rectangle -- Pointer to a struct Rectangle to fill in. The contents will take the size of the icon image, the icon border size and -- if you provide RastPort and label text -- the icon label into account. Due to how labels are printed, the rectangle->MinX and rectangle->MinY members may be negative. tags -- Additional drawing options to be taken into account. TAGS ICONDRAWA_DrawInfo (struct DrawInfo *) -- Drawing information data associated with the RastPort parameter passed in. This tag defaults to NULL. ICONDRAWA_Borderless (BOOL) -- When calculating the size of the rectangle, this tag allows you to leave the icon border size out of the equation. This tag defaults to FALSE. ICONDRAWA_Width (ULONG) -- The width for the icon to be drawn. See DrawIconStateA(). (V51) This tag defaults to zero (original width). ICONDRAWA_Height (ULONG) -- The height for the icon to be drawn. See DrawIconStateA(). (V51) This tag defaults to zero (original height). ICONDRAWA_SizeBounds (struct Rectangle *) -- The size limits for the icon to be drawn. See DrawIconStateA(). (V53) This tag defaults to NULL, which means { 8, 8, 256, 256 }. ICONDRAWA_AllowUpscaling (BOOL) -- Enforce the minimum size specified with ICONDRAWA_SizeBounds even when the icon's original size is already smaller than that. See DrawIconStateA(). (V53) This tag defaults to FALSE. ICONDRAWA_Borders (struct Rectangle *) -- The size of the (possibly invisible) borders around the icon to be drawn, overriding the global icon border sizes set via ICONCTRLA_SetGlobalEmbossRect. See DrawIconStateA(). (V53) This tag defaults to NULL (use global border sizes). RESULTS success -- TRUE if the parameters were well-formed and the output data fits into the Rectangle data structure (which may not be the case if the image is too large for a signed 16 bit integer to hold). EXAMPLE /* Find out how large an icon is. */ struct DiskObject *icon; struct Rectangle rect; if(GetIconRectangleA(NULL,NULL,icon,NULL,&rect,NULL)) { LONG width,height; width = rect.MaxX - rect.MinX + 1; height = rect.MaxY - rect.MinY + 1; Printf("icon is %ld×%ld pixels in size.\n", width,height); } /* Find out which area the icon rendering would * cover if a label would be printed below it. */ struct RastPort *rp; if(GetIconRectangle(rp,NULL,icon,"a rather long label text",&rect,TAG_DONE)) { Printf("icon plus label would cover the area %ld,%ld×%ld,%ld\n", rect.MinX,rect.MinY,rect.MaxX,rect.MaxY); } NOTES This function can be used to optimize on-screen rendering by precalculating the area rendering would cover. To make sure that the precalculated area size matches the one covered by the actual drawing operation, the RastPorts you use for measuring and for drawing should share the same font and the same text styles. The image size calculated by this function can be slightly larger than the data you will find in the icon's do_Gadget.GadgetRender Image structure since the icon border will be taken into account. This happens regardless of whether icon.library was switched into frameless icon rendering mode or whether the icon is frameless. To obtain the size of the icon without taking the border into account, use the ICONDRAWA_Borderless tag. The size of the icon, as returned by this function, may be different depending upon whether LayoutIconA() has been called or not. SEE ALSO workbench/icon.h workbench/workbench.h icon.library/DrawIconState icon.library/IconControlA icon.library/LayoutIconA icon.library/GetIconTagList icon.library/GetIconTagList NAME GetIconTagList -- Retrieve an icon (V44) SYNOPSIS icon = GetIconTagList(name,tags); struct DiskObject * GetIconTagList(STRPTR name,struct TagItem *tags); icon = GetIconTags(name,tag1,...); struct DiskObject * GetIconTags(STRPTR name,Tag tag1,...); FUNCTION This function is used to retrieve an icon; the icon can belong to a file/drawer/volume or it can be a default icon. INPUTS name -- Name of the object an icon is to be retrieved for, or NULL if a default icon is to be retrieved. tags -- Retrieval options. TAGS ICONGETA_GetDefaultType (LONG) -- Type of the default icon to retrieve; must be one of WBDISK, WBDRAWER, WBTOOL, WBPROJECT, WBGARBAGE, WBDEVICE or WBKICK. If this tag is used, the "name" parameter will be ignored. ICONGETA_GetDefaultName (STRPTR) -- Name of the default object type to retrieve a default icon for. If the named default icon cannot be found, NULL will be returned. To avoid this, also specify ICONGETA_GetDefaultType: this will provide a fall-back and return a "default" default icon instead. If this tag is used, the "name" parameter will be ignored. ICONGETA_FailIfUnavailable (BOOL) -- If there is no icon for the specified object, this tag will control how to proceed: if ICONGETA_FailIfUnavailable is set to TRUE, NULL and an error code will be returned; if set to FALSE, icon.library will first invoke the global identification hook (see icon.library/IconControlA) and then, if necessary, provide a default icon for the object in question. This tag defaults to TRUE. ICONGETA_GetPaletteMappedIcon (BOOL) -- By default, icon.library will try to retrieve the palette mapped version of an icon. To change this, set the ICONGETA_GetPaletteMappedIcon tag to FALSE. This tag defaults to TRUE. ICONGETA_RemapIcon (BOOL) -- Palette mapped icons will usually be automatically remapped for display on the screen selected using IconControlA(). If you do not want this to happen because, for example, you want to use LayoutIcon() instead, you can set the ICONGETA_RemapIcon tag to FALSE. Note: with older versions of the library, when doing this the icon returned to you would have NULL pointers in the do_Gadget.GadgetRender and do_Gadget.SelectRender members. This no longer happens starting with icon.library 44.505. This tag defaults to TRUE. ICONGETA_IsDefaultIcon (LONG *) -- When retrieving an icon with the ICONGETA_FailIfUnavailable tag set to FALSE, you may receive a default icon because there is no on-disk icon file for the object you wanted to retrieve it for. This type of default icon is also known as a "fake" icon. To find out whether you have received a fake icon, use the ICONGETA_IsDefaultIcon tag. ICONGETA_GenerateImageMasks (BOOL) -- When loading icons with transparent colours or backfill imagery, bit plane masks will be generated for later use with DrawIconStateA(). If you do not need these masks, set this tag to FALSE. This tag defaults to TRUE. ICONGETA_Screen (struct Screen *) -- Pointer to the screen to remap the icon to; if set to NULL, the icon will be remapped to a default four-color palette. Note: with older versions of the library, setting this to NULL would keep the icon from getting remapped in the first place, causing the function to fail. This no longer happens starting with icon.library 44.492. This tag defaults to the default screen to remap to, as preset by IconControlA(). ICONGETA_Label (STRPTR) -- The label text to be printed below the icon when it is put to use lateron. This parameter can be useful to figure out the type of the icon to be retrieved by the identification hook. For example, Workbench may label unreadable disk icons as "DF0:????". The identification hook could key on this and supply an appropriate icon for the disk. This tag defaults to NULL. ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to store error codes in. Note that this variable will be initialized regardless of whether an error occured or not. Thus, you can check for an error condition by comparing the variable contents against 0; 0 indicates success, all other values are error codes as defined by dos.library. ICONGETA_UseFriendBitMap (BOOL) -- If set to TRUE, all BitMap allocations done by icon.library will be done with a friend BitMap as a reference (see graphics.library/AllocBitMap). This also means that the images in icon->do_Gadget.GadgetRender and icon->do_Gadget.SelectRender are BOOPSI objects and not traditional planar images. (V50) This tag defaults to FALSE. ICONGETA_FileFormat (STRPTR *) -- Returns the format of the file the icon is loaded from. If the file is in native Amiga format, the returned name will be "Amiga". (V51) ICONGETA_Width (UWORD) -- Request a specific width for the icon to be loaded. If the icon is supplied by an external loader module which supports scaling (e.g. a vector icon loader) the result will be an icon of the requested width. Otherwise, the requested width will be ignored, unless you also pass ICONGETA_ForceScaling with a TRUE value, in which case icon.library will perform a manual bitmap rescaling of the icon's imagery in order to satisfy the request. You can request either an exact width, or a percentage of the original width with the SIZEPERC() macro defined in . If you pass -1 (~0UL) for the width, and are also requesting a specific height with ICONGETA_Height, the new width will be calculated so that the original icon's aspect ratio is preserved. Note: once rescaled by icon.library, the original icon image data is lost, and the scaled imagery will be saved the next time the icon is written back do disk. If you need a scaled version of the icon's imagery for rendering purposes only, you might prefer to use ICONDRAWA_Width and ICONDRAWA_Height with DrawIconStateA() instead, which won't affect the normal image data. (V51) This tag defaults to zero, which means not to change the original width of the icon. ICONGETA_Height (UWORD) -- Request a specific height for the icon to be loaded. If the icon is supplied by an external loader module which supports scaling (e.g. a vector icon loader) the result will be an icon of the requested height. Otherwise, the requested height will be ignored, unless you also pass ICONGETA_ForceScaling with a TRUE value, in which case icon.library will perform a manual bitmap rescaling of the icon's imagery in order to satisfy the request. You can request either an exact height, or a percentage of the original height with the SIZEPERC() macro defined in . If you pass -1 (~0UL) for the height, and are also requesting a specific width with ICONGETA_Width, the new height will be calculated so that the original icon's aspect ratio is preserved. Note: once rescaled by icon.library, the original icon image data is lost, and the scaled imagery will be saved the next time the icon is written back do disk. If you need a scaled version of the icon's imagery for rendering purposes only, you might prefer to use ICONDRAWA_Width and ICONDRAWA_Height with DrawIconStateA() instead, which won't affect the normal image data. (V51) This tag defaults to zero, which means not to change the original height of the icon. ICONGETA_ForceScaling (BOOL) -- Tell icon.library to perform a manual bitmap rescaling of the loaded icon if it doesn't already have the size requested with ICONGETA_Width and ICONGETA_Height. (V51) This tag defaults to FALSE. ICONGETA_SizeBounds (struct Rectangle *) -- Specify the size limits for the icon to be loaded. It will never end up being larger than the maximum width and height, nor smaller than the minimum width and height (unless it's already smaller than that at its original size, in which case the original size will also become the minimum size). If the icon's size (either original, or requested via the ICONGETA_Width/ICONGETA_Height tags) doesn't respect the specified bounds, the icon image will be scaled up or down accordingly; the expected aspect ratio will be preserved whenever possible. (V53) This tag defaults to NULL, which means 8x8 for the minimum width/height and 256x256 for the maximum width/height. The bounds are passed as a Rectangle structure with the minimum sizes in MinX and MinY, and the maximum sizes in MaxX and MaxY. ICONGETA_AllowUpscaling (BOOL) -- Tell icon.library to enforce the minimum size specified with ICONGETA_SizeBounds even when the icon's original size is already smaller than that. This means the icon image may be made larger even if no upscaling was explicitly requested. By default this doesn't happen as icon images designed for a certain size don't usually look very good if scaled up. (V53) This tag defaults to FALSE. RESULT icon -- Pointer to a struct DiskObject or NULL in case of error. You can use IoErr() to retrieve the error code or use the ICONA_ErrorCode tag instead. EXAMPLE /* Retrieve the default drawer icon. */ struct DiskObject *icon; LONG errorCode; icon = GetIconTags(NULL, ICONGETA_GetDefaultType,WBDRAWER, ICONA_ErrorCode,&errorCode, TAG_DONE); if(icon == NULL) { Printf("could not retrieve default drawer icon;\n"); PrintFault(errorCode,NULL); } /* Retrieve the default "picture" icon. */ icon = GetIconTags(NULL, ICONGETA_GetDefaultName,"picture", TAG_DONE); /* Retrieve the default "picture" icon; if there is no * such default icon, retrieve the default project * icon instead. */ icon = GetIconTags(NULL, ICONGETA_GetDefaultName,"picture", ICONGETA_GetDefaultType,WBPROJECT, TAG_DONE); /* Retrieve the regular, non-palette-mapped version of * an icon. */ icon = GetIconTags("file", ICONGETA_GetPaletteMappedIcon,FALSE, TAG_DONE); /* Retrieve the icon for a file; if there is no icon associated * with it, retrieve a default icon that matches the file. * Also, remember whether we got a real icon or a fake one. */ LONG isFakeIcon; icon = GetIconTags("file", ICONGETA_FailIfUnavailable,FALSE, ICONGETA_IsDefaultIcon,&isFakeIcon, TAG_DONE); if(icon != NULL) { Printf("got an icon at 0x%08lx, and it is a %s icon.\n", icon,isFakeIcon ? "fake" : "real"); } NOTES This function is a superset of GetDefDiskObject(), GetDiskObject() and GetDiskObjectNew(). If a palette-mapped icon is set to allocate its colours from the default screen, such as the Workbench screen, icon.library may resort to remap its colours in the course of Workbench screen close/reopen transitions. This means that you cannot depend upon the icon's image bitmaps to stay the same size, shape or colour. If this is what you need, you should either create your own images from the palette mapped data or make copies of the icon image bitmaps and the associated colour table. If during Workbench close/open transitions the global remap screen becomes NULL, GetIconTagList() may refuse to return a remapped icon and return with an error (ERROR_REQUIRED_ARG_MISSING) instead. SEE ALSO workbench/icon.h workbench/workbench.h icon.library/GetDiskObject icon.library/GetDiskObjectNew icon.library/GetDefDiskObject icon.library/IconControlA icon.library/PutIconTagList icon.library/IconControlA icon.library/IconControlA NAME IconControlA -- Set and get icon and icon.library options (V44) SYNOPSIS processed = IconControlA(icon,tags); ULONG IconControlA(struct DiskObject *,struct TagItem *); processed = IconControl(icon,tag1,...); ULONG IconControl(struct DiskObject *,Tag tag1,...); FUNCTION This function is used to modify and query icon and icon.library options. INPUTS icon -- Pointer to a struct DiskObject, or NULL if global options are to be modified/queried. tags -- Options to modify/query. TAGS ICONCTRLA_SetGlobalScreen (struct Screen *) -- Pointer to the screen to remap palette mapped icons to. This is commonly used by workbench.library after it has initialized itself and before/after screen open/close transitions. If the screen is set to NULL, the icon colour remapping strategy is changed: colours are no longer allocated from a screen and the colours to map to will come from a default colour colour table with four palette entries. Please note that once you select a screen to remap to, you cannot tell icon.library to use a different screen; you first need to tell icon.library to "let go" of the previously selected screen by passing a NULL ICONCTRLA_SetGlobalScreen parameter. You can set a different screen only after this is done. ICONCTRLA_GetGlobalScreen (struct Screen **) -- Pointer to the screen to remap palette mapped icons to. ICONCTRLA_SetGlobalPrecision (LONG) -- Set the global colour allocation precision used when remapping icons for display. Default is PRECISION_ICON. OBP_Precision (LONG) -- Can be used as an alias for the ICONCTRLA_SetGlobalPrecision tag. ICONCTRLA_GetGlobalPrecision (LONG *) -- Get the global colour allocation precision used when remapping icons for display. ICONCTRLA_SetGlobalEmbossRect (struct Rectangle *) -- Set the frame sizes used for drawing icons. The Rectangle must be initialized as follows: Rectangle->MinX Width of left edge border (negative), must be in the range [-255..-1] Rectangle->MinY Height of top edge border (negative), must be in the range [-255..-1] Rectangle->MaxX Width of right edge border (positive), must be in the range [1..255] Rectangle->MaxY Height of bottom edge border (positive), must be in the range [1..255] ICONCTRLA_GetGlobalEmbossRect (struct Rectangle *) -- Get the frame sizes used for drawing icons. ICONCTRLA_SetGlobalFrameless (BOOL) -- Select whether icons should always be drawn without a surrounding frame. This option defaults to FALSE. ICONCTRLA_GetGlobalFrameless (LONG *) -- Query whether icons are always drawn without a surrounding frame. ICONCTRLA_SetGlobalIdentifyHook (struct Hook *) -- Set the hook that is invoked when trying to find an icon for a file/drawer/volume that does not have an icon associated with it. If set to NULL, no hook will be called. The hook will be called with the following parameters: hookFunc(hook,reserved,iim) A0 A2 A1 VOID hookFunc(struct Hook *hook,APTR reserved, struct IconIdentifyMsg *iim); The reserved parameter will be set to NULL (V44). The icon identification message contents are as follows: iim_SysBase iim_DOSBase iim_UtilityBase iim_IconBase Library base pointers set up for your use. iim_FileLock A lock on the object to return an icon for. This lock is guaranteed to be non-NULL. iim_ParentLock A lock on the object's parent directory. This may be NULL if iim_FileLock points to a volume's root directory. In such a case you should return a WBDISK type icon instead of a WBDRAWER icon. iim_FIB An initialized FileInfoBlock structure; prior to passing iim_FIB to you, Examine(iim_FileLock,iim_FIB) was called. Unlike the other members of this data structure, you may modify the contents of iim_FIB. iim_FileHandle If the object to return an icon for is a file, this member will contain a file handle that can be used to Read() its contents. The file read position will be set to the beginning of the file. Note that this member can be NULL. iim_Tags A copy of the tag item list passed to GetIconTagList(); if you are going to call GetIconTagList() in your hook, be sure to include this list as part of the tag list you pass to it. NOTE: This list does not include the tag ICONA_FailIfUnavailable. Keep in mind that the use of this tag can trigger a recursion if the icon you tried to retrieve via GetIconTagList() does not exist: your hook code will be invoked again. With the exception of iim_FIB, all members of the IconIdentifyMsg are read-only; you may pass them to functions like Read(), Examine(), etc. but you may not Close() files, UnLock() locks or perform other functions that may result in the data structures getting deallocated or trashed. When you manage to find the right icon type for the object to be examined, you should return a pointer to a struct DiskObject that can be freed using FreeDiskObject() lateron. Note that you cannot just return a pointer to a statically initialized data structure in your code, you must return a pointer to a DiskObject allocated by icon.library itself, such as through GetIconTagList(), DupDiskObjectA() or NewDiskObject(). The icon you return will be checked to make sure that its type matches the corresponding object. For example, returning a WBDRAWER icon for a volume root directory will cause that icon to be released and to be ignored. ICONCTRLA_GetGlobalIdentifyHook (struct Hook **) -- Get the hook that is invoked when trying to find an icon for a file/drawer/volume that does not have an icon associated with it. ICONCTRLA_SetGlobalMaxNameLength (LONG) -- icon.library has a built-in file name length limit that affects whether icon files are read and written. Currently, the default for this value is 25 characters. This is sufficient for an icon file name acceptable with the ROM filing system. This limit has two effects: if an icon file is to be written whose name would be longer than the limit, icon.library will silently abort the write attempt and pretend that the icon file has been written; this is done in order to avoid overwriting the original data file with the icon file. If an icon file was read that turns out to contain invalid icon data, another test is done in order to find out whether the file name was longer than the limit. If this is the case, it is assumed that the data was read from the original file rather than from the icon file. The library then pretends that the icon file was not found. This tag can be used to set this length limit. The limit must be in the range [8..255]. ICONCTRLA_GetGlobalMaxNameLength (LONG *) -- Retrieve the file name length limit used by icon.library. ICONCTRLA_SetGlobalNewIconsSupport (BOOL) -- Select whether icon.libray should read and return coloured icon images stored in NewIcons format. This option defaults to TRUE. ICONCTRLA_GetGlobalNewIconsSupport (LONG *) -- Query whether icon.library will read and return coloured icon images stored in NewIcons format. ICONCTRLA_SetGlobalColorIconSupport (BOOL) -- Select whether icon.library should read and return coloured icon images. This option defaults to TRUE. ICONCTRLA_GetGlobalColorIconSupport (LONG *) -- Query whether icon.library will read and return coloured icon images. ICONCTRLA_SetGlobalLeftOutMarking (BOOL) -- Select whether icons with the ICON_LEFTOUT property should be drawn with a special mark (typically a small user-customizable symbol) for better visual identification. (V51) This option defaults to FALSE. ICONCTRLA_GetGlobalLeftOutMarking (LONG *) -- Query whether icons with the ICON_LEFTOUT property will be drawn with a special mark (typically a small user-customizable symbol) for better visual identification. (V51) ICONCTRLA_SetGlobalSelectEffect (ULONG) -- Select the graphic effect icon.library should perform on the regular image of an icon to represent it in selected state, when the icon doesn't have a real alternate image of its own. This setting only affects palette mapped and direct mapped icons having a single image. See for the available select effects. (V51) This option defaults to SEL_DARKEN with a darkening amount of 40. ICONCTRLA_GetGlobalSelectEffect (ULONG *) -- Get the graphic effect icon.library will perform on the regular image of an icon to represent it in selected state, when the icon doesn't have a real alternate image of its own. (V51) ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to store error codes in. Note that this variable will be initialized regardless of whether an error occured or not. Thus, you can check for an error condition by comparing the variable contents against 0; 0 indicates success, all other values are error codes as defined by dos.library. ICONA_ErrorTagItem (struct TagItem **) -- When an error occurs whilst processing the tag item list passed to IconControl(), you can have a pointer to the item that caused the error passed back via the ICONA_ErrorTagItem tag. Note that for TagItem lists allocated from the stack the address passed back to you may no longer be valid when control returns from IconControl(). The following tags need a valid icon parameter to operate on. If the parameter is missing or invalid, it will be registered as an error. ICONCTRLA_GetImageMask1 (PLANEPTR *) -- Pointer to the mask plane for the regular icon image (icon->do_Gadget.GadgetRender). Note that this may be NULL. ICONCTRLA_GetImageMask2 (PLANEPTR *) -- Pointer to the mask plane for the alternate icon image (icon->do_Gadget.SelectRender). Note that this may be NULL. ICONCTRLA_SetTransparentColor1 (LONG) -- Set the transparent colour for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). The colour must be among the valid palette entries, e.g. for a 16 colour image, the transparent colour may not be larger than 15. To make the icon image opaque, set its transparent colour to -1. ICONCTRLA_GetTransparentColor1 (LONG *) -- Get the transparent colour for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). If the image is opaque, its "transparent colour" will be returned as -1. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. ICONCTRLA_SetTransparentColor2 (LONG) -- Set the transparent colour for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). The colour must be among the valid palette entries, e.g. for a 16 colour image, the transparent colour may not be larger than 15. To make the icon image opaque, set its transparent colour to -1. Please note that you can set the alternate image transparent colour only if there is an alternate image. ICONCTRLA_GetTransparentColor2 (LONG *) -- Get the transparent colour for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). If the image is opaque, its "transparent colour" will be returned as -1. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. Likewise, if there is no alternate image, no information may be available. ICONCTRLA_SetPalette1 (struct ColorRegister *) -- Set the colour palette for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). ICONCTRLA_GetPalette1 (struct ColorRegister **) -- Get the colour palette for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. Note that the number of palette entries in this table matches the number of colours in use when the icon was first created. ICONCTRLA_SetPalette2 (struct ColorRegister *) -- Set the colour palette for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). ICONCTRLA_GetPalette2 (struct ColorRegister **) -- Get the colour palette for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. If there is no alternate image, no information may be available. Note that the number of palette entries in this table matches the number of colours in use when the icon was first created. ICONCTRLA_SetPaletteSize1 (ULONG) -- Set the size of the colour palette to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). This value must be in the range [1..256]. ICONCTRLA_GetPaletteSize1 (ULONG *) -- Get the size of the colour palette to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. ICONCTRLA_SetPaletteSize2 (ULONG) -- Set the size of the colour palette to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). This value must be in the range [1..256]. ICONCTRLA_GetPaletteSize2 (ULONG *) -- Get the size of the colour palette to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. If there is no alternate image, no information may be available. ICONCTRLA_SetImageData1 (UBYTE *) -- Set the image data to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). There must be exactly as many bytes of image data as the image width multiplied by its height requires. To drop the palette mapped image data associated with an icon, use "ICONCTRLA_SetImageData1,NULL,". ICONCTRLA_GetImageData1 (UBYTE **) -- Get the image data to be used for a palette mapped icon image, in this case the regular icon image (icon->do_Gadget.GadgetRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. ICONCTRLA_SetImageData2 (UBYTE *) -- Set the image data to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). There must be exactly as many bytes of image data as the image width multiplied by its height requires. To drop the palette mapped image data associated with the alternate image of an icon, use "ICONCTRLA_SetImageData2,NULL,". ICONCTRLA_GetImageData2 (UBYTE **) -- Get the image data to be used for a palette mapped icon image, in this case the alternate icon image (icon->do_Gadget.SelectRender). Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. If there is no alternate image, no information may be available. ICONCTRLA_SetFrameless (BOOL) -- Select whether the icon should be drawn without a frame. This option defaults to FALSE. ICONCTRLA_GetFrameless (LONG *) -- Query whether the icon should be drawn without a frame. ICONCTRLA_SetNewIconsSupport (BOOL) -- Select whether palette mapped icon images that were originally stored in NewIcons format should be written back in the same format. This option defaults to TRUE. ICONCTRLA_GetNewIconsSupport (LONG *) -- Query whether palette mapped icon images that were originally stored in NewIcons format should be written back in the same format. ICONCTRLA_SetAspectRatio (UBYTE) -- Set the icon aspect ratio; this consists of a numerator and a denominator packed into a single byte (the PACK_ICON_ASPECT_RATIO() macro can be used for encoding this parameter). If the icon aspect ratio is unknown, ICON_ASPECT_RATIO_UNKNOWN should be used. ICONCTRLA_GetAspectRatio (UBYTE *) -- Get the icon aspect ratio; this consists of a numerator and a denominator packed into a single byte (the UNPACK_ICON_ASPECT_RATIO() macro can be used for decoding this value). If the icon aspect ratio is unknown, ICON_ASPECT_RATIO_UNKNOWN will be returned. ICONCTRLA_SetWidth (ULONG) -- Select the palette mapped icon image width. This value must be in the range [1..256]. ICONCTRLA_GetWidth (ULONG *) -- Query the palette mapped icon image width. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. ICONCTRLA_SetHeight (ULONG) -- Select the palette mapped icon image height. This value must be in the range [1..256]. ICONCTRLA_GetHeight (ULONG *) -- Query the palette mapped icon image height. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. ICONCTRLA_IsPaletteMapped (LONG *) -- Query whether the icon is using palette mapped icon images. FALSE will be returned if the icon is using simple bitmapped images or direct mapped (truecolor) images. ICONCTRLA_IsNewIcon (LONG *) -- Query whether the icon is of the NewIcon type. ICONCTRLA_IsNativeIcon (LONG *) -- There is an important difference between struct DiskObject icons allocated by icon.library itself (these are the so-called "native" icons) and statically initialized icons which consist solely of a simple struct DiskObject which may be part of a program's static data area. For example, you can attach a palette mapped icon image to a "native" icon, which is something you cannot do with a statically allocated icon. To help you tell the two types apart, you can use the ICONCTRLA_IsNativeIcon query tag. ICONGETA_IsDefaultIcon (LONG *) -- Query whether this icon is associated with a file/drawer/volume or is a "fake" icon that was constructed for an object that has no icon associated with it. ICONCTRLA_GetScreen (struct Screen **) -- Get the screen this icon has been remapped to and whose colour map it uses. Note that this data is valid only for palette mapped icons; for other types, you may not receive any meaningful result. This tag may return NULL if the icon is not currently associated with a screen. ICONCTRLA_HasRealImage2 (LONG *) -- icon.library may generate an alternate image for palette mapped icons if there is no image data stored for this image. To find out whether an icon was generated or is part of the original icon image, use the ICONCTRLA_HasRealImage2 tag. ICONCTRLA_GetBitMap1 (struct BitMap *) -- Get a bitmap pointer to the icon image stored in icon->do_Gadget.GadgetRender. (V50) ICONCTRLA_GetBitMap2 (struct BitMap *) -- Get a bitmap pointer to the icon image stored in icon->do_Gadget.SelectRender. (V50) ICONCTRLA_UseFriendBitMap (BOOL) -- If set to TRUE, all BitMap allocations done by icon.library will be done with a friend BitMap as a reference (see graphics.library/AllocBitMap). This also means that the images in icon->do_Gadget.GadgetRender and icon->do_Gadget.SelectRender are BOOPSI objects and not traditional planar images. Defaults to FALSE. (V50) ICONCTRLA_SetImageDataFormat (ULONG) -- Set the format of the icon's image data, possibly resetting its imagery if a change of format is performed. You can set the icon as bitmapped (which will drop all chunky image data associated to it), as palette mapped (the 8-bit CLUT chunky format introduced in V44), or as direct mapped (the 32-bit ARGB chunky format introduced in V51). If you change the format to palette mapped or direct mapped from a different format, the icon's chunky image data will be reset to a default image (a small white square) until you inject new image data in the specified format; the icon's actual appearance won't change until the next icon layout operation, however. If you change the format to bitmapped from a different format, all the chunky data will be lost and the icon's appearance will immediately revert to that of an old-style four-color planar icon. Make sure you pass the correct type of chunky image data to the icon with ICONCTRLA_SetImageData1 and ICONCTRLA_SetImageData2 once you've set the icon's image data format with this tag: the palette mapped format requires an array of indices into a color table (one byte per pixel) while the direct mapped format requires an array of ARGB longwords (four bytes per pixel), i.e. a full truecolor image with alpha channel. (V51) ICONCTRLA_GetImageDataFormat (ULONG *) -- Get the format of the icon's image data, which can be IDFMT_BITMAPPED (an old-style planar icon) IDFMT_PALETTEMAPPED (a CLUT chunky icon), or IDFMT_DIRECTMAPPED (a truecolor chunky icon). This tag supersedes ICONCTRLA_IsPaletteMapped to obtain complete information on an icon's image data format. (V51) ICONCTRLA_GetIconFileFormat (STRPTR *) -- Get the format of the file an icon was loaded from. If the icon is not recognized by icon.library nor by any of the icon loader modules an error will be returned, otherwise a pointer to a read-only string with the file format name. For icons loaded from a native Amiga icon file, the returned string will be "Amiga". (V51) ICONCTRLA_AddScaledSize (ULONG) -- Generate a scaled version of the icon's imagery. Pass the requested width and height as two UWORDs packed in a single ULONG; you can specify either exact sizes or a percentage of the normal sizes with the ICONSIZE() or ICONSCALE() macros defined in . The scaled imagery will be cached in order to speed up any subsequent DrawIconStateA() calls; you can get rid of it (and free all of its memory) with the ICONCTRLA_RemScaledSize tag. Note: the scaled imagery will reflect the icon's appearance at the time it is generated. It will also be updated after each icon layout, which may be time-consuming if the icon has many scaled sizes attached. Therefore, it is advised you remove any existing scaled size via ICONCTRLA_RemScaledSize as soon as it is no longer needed. (V51) ICONCTRLA_RemScaledSize (ULONG) -- Remove a particular scaled version of the icon's imagery, and free all memory associated with it. You should specify the size as two UWORDs (width and height) packed in a single ULONG, just like for the ICONCTRLA_AddScaledSize tag. (V51) RESULT processed -- Number of tags that were processed correctly, i.e. the number of tags whose parameters are in order, for which information could be returned, etc. If processing stops because of an error, the number returned by this function will be smaller than the number of tag items passed in. The same happens if the information you wanted to obtain is unavailable. In any case, check the error code this routine can set up for you. EXAMPLE /* Check if the icon is palette mapped. */ LONG isPaletteMapped; LONG errorCode; struct DiskObject *icon; if(IconControl(icon, ICONCTRLA_IsPaletteMapped,&isPaletteMapped, ICONA_ErrorCode,&errorCode, TAG_DONE) == 1) { Printf("the icon %s palette mapped\n", isPaletteMapped ? "is" : "is not"); } else { Printf("could not query icon information;\n"); PrintFault(errorCode,NULL); } /* Set the icon colour remapping precision. */ IconControl(NULL, ICONCTRLA_SetGlobalPrecision,PRECISION_EXACT, TAG_DONE); /* Query the embossing rectangle dimensions and * the identification hook. */ struct Rectangle rect; struct Hook *hook; if(IconControl(NULL, ICONCTRLA_GetGlobalEmbossRect,&rect, ICONCTRLA_GetGlobalIdentifyHook,&hook, TAG_DONE) == 2) { Printf("embossing rect: %ld,%ld,%ld,%ld\n", rect.MinX,rect.MaxX,rect.MinY,rect.MaxY); Printf("identification hook: 0x%08lx\n", hook); } NOTES Changing an icon's palette or image data does not automatically produce a different icon image you can use. To do this, you must re-layout it using LayoutIcon(). When querying parameters, make sure to always pass in a pointer to a LONG word variable to store the result in. Some get/set operations may cause additional memory to be allocated. This may fail; be prepared. IconControl() processes the tag item list in sequential order. This has consequences for several tags, such as the palette size and the transparent colour. For example, if you want to make colour #14 of an icon image transparent, make sure to have the palette size set to at least 15 colours before you try to change the transparent colour. Otherwise, IconControl() may refuse to set the transparent colour to #14 since it won't know that there should be more than 14 colours in that image at the time you try to set it. Therefore, if you wanted to change the palette size and the transparent colour in the same tag item list, make sure that the palette size change tag appears before the transparent colour change tag. As described above, some of the operations on icons are not supported for DiskObjects not allocated through icon.library. In such cases you will receive an error code ERROR_ACTION_NOT_KNOWN. When you set an icon's palette or image data (with one of the following tags: ICONCTRLA_SetPalette1, ICONCTRLA_SetPalette2, ICONCTRLA_SetImageData1, ICONCTRLA_SetImageData2), icon.library will only update the respective data pointers in the icon, it will not copy the data pointed to. This means that the palette and image data information must stay valid until the icon they are attached to is disposed of. If you want to play it safe and be able to release the palette and image data as soon as possible, make a copy of the icon with icon.library/DupDiskObjectA. When you create a palette mapped icon from an old one, make sure that if your new icon should use only a single icon image the second image needs to be set to NULL. Otherwise, the image data the icon started with will remain attached to it. Since the new icon size may not match the old icon size the result may not look too pretty. To tell icon.library that the second image is not needed use "IconControl(icon,ICONCTRLA_SetImageData2,NULL,TAG_DONE);". SEE ALSO dos.library/IoErr icon.library/DupDiskObjectA icon.library/GetIconTagList icon.library/LayoutIcon icon.library/NewDiskObject graphics.library/BltMaskBitMapRastPort graphics.library/ObtainBestPenA utility.library/CallHookPkt graphics/view.h workbench/icon.h workbench/workbench.h icon.library/LayoutIconA icon.library/LayoutIconA NAME LayoutIconA -- Adapt a palette-mapped icon for display (V44) SYNOPSIS success = LayoutIconA(icon,screen,tags); BOOL LayoutIconA(struct DiskObject *icon,struct Screen *screen, struct TagItem *tags); success = LayoutIcon(icon,screen,...); BOOL LayoutIcon(struct DiskObject *icon,struct Screen *screen,...); FUNCTION This function will prepare an icon for display, either on a specific screen or using a default colour palette. It is useful only for palette mapped icons. INPUTS icon -- The icon to be remapped. This must be a palette mapped icon. screen -- Pointer to a screen to remap the icon for or NULL to remap the icon to use the system default colour palette or something very similar to it (this means: four colours only). Starting with version 53.5, you can also pass ~0UL which means the global default screen. In this case, you should expect that your icon may get changed and remapped again during Workbench close/open transitions, unless you explicitly prevent it by locking the Workbench screen. tags -- Additional rendering options. TAGS OBP_Precision (LONG) -- Pen colour allocation precision. Default is the same precision as set in the global icon.library settings (see IconControlA()). ICONLAYA_UseFriendBitMap (BOOL) -- If TRUE, the remapping will generate a bitmap which is "friend" of the screen bitmap, no pens will be allocated on hicolor/truecolor screens, and the GadgetRender/SelectRender fields will be BOOPSI images. (V50) OUTPUTS success -- TRUE if the icon could be remapped, FALSE if the remapping failed for some reason. In case of of failure, icon.library will try its best to keep the icon in a presentable state, but this may fail. In case of failure, the error code can be retrieved using dos.library/IoErr. NOTES You must make sure that the screen you remap to does not go away while there is an icon to use its colours. For a public screen, the easiest way to guarantee this is to keep it locked (see intuition.library/LockPubScreen). For custom screens, just don't close them! If you have to close the screen or need to keep your icon around until after a screen is closed, you should call LayoutIcon() with a NULL screen parameter. This will release all pens the icon has allocated and remap the icon to a default set of colours. Alternatively, you can dispose of the icon via FreeDiskObject() which will also release all pens the icon has allocated, including the icon itself, of course. Icons remapped to the global default screen (normally, that would be the Workbench screen) may get changed and remapped again during Workbench close/open transitions. To prevent this from taking place, just make sure that the Workbench screen does not close (e.g. via LockPubScreen("Workbench")). The sizes of the bitmapped icon imagery and the palette mapped icon imagery may not agree. Thus, the size of the icon may be reported differently before and after LayoutIconA() is called. Therefore, don't cache the icon size if you must call LayoutIconA()! First call LayoutIconA(), then determine the size of the icon. Also, don't change the GadgetRender and SelectRender fields to point to custom imagery if the icon is going to be remapped; if you really need to do that, make sure you reset them to their original values (as set by icon.library) before calling the LayoutIcon() function on the icon. SEE ALSO dos.library/IoErr graphics.library/ObtainBestPenA graphics.library/ReleasePen icon.library/FreeDiskObject icon.library/GetIconRectangleA icon.library/GetIconTagList icon.library/IconControl intuition.library/LockPubScreen intuition.library/UnlockPubScreen graphics/view.h icon.library/MatchToolValue icon.library/MatchToolValue NAME MatchToolValue - check a tool type variable for a particular value. SYNOPSIS result = MatchToolValue(typeString, value) BOOL MatchToolValue(STRPTR, STRPTR); FUNCTION MatchToolValue is useful for parsing a tool type value for a known value. It knows how to parse the syntax for a tool type value (in particular, it knows that '|' separates alternate values). Note that the parsing is case insensitive. INPUTS typeString -- a ToolType value (as returned by FindToolType) value -- you are interested if value appears in typeString RESULTS result -- TRUE if the value was in typeString else FALSE. EXAMPLE Assume there are two type strings: type1 = "text" type2 = "a|b|c" MatchToolValue( type1, "text" ) returns TRUE MatchToolValue( type1, "TEXT" ) returns TRUE MatchToolValue( type1, "data" ) returns FALSE MatchToolValue( type2, "a" ) returns TRUE MatchToolValue( type2, "b" ) returns TRUE MatchToolValue( type2, "d" ) returns FALSE MatchToolValue( type2, "a|b" ) returns FALSE NOTES icon.library V44 skips blank spaces surrounding the typeString options and the value string. Older icon.library versions did not support this. SEE ALSO icon.library/FindToolType utility.library/Stricmp icon.library/NewDiskObject icon.library/NewDiskObject NAME NewDiskObject -- Create an empty icon (V44) SYNOPSIS icon = NewDiskObject(type) struct DiskObject * NewDiskObject(LONG type); FUNCTION This function is used to create an "empty" DiskObject structure, which has no image data associated with it. Still, all the necessary structures are in place, you just have to fill them in. INPUTS type -- Icon type to create, this must be one of WBDISK, WBDRAWER, WBTOOL, WBPROJECT, WBGARBAGE, WBDEVICE or WBKICK. RESULT icon -- Pointer to a struct DiskObject or NULL in case of error. You can use IoErr() to retrieve the error code. NOTES The DiskObject returned by this function will have a zero width and height Image in the do_Gadget.GadgetRender member and the do_Gadget.Width/do_Gadget.Height members will both be 0, too. SEE ALSO dos.library/IoErr workbench/icon.h workbench/workbench.h icon.library/PutDefDiskObject icon.library/PutDefDiskObject NAME PutDefDiskObject - write disk object as the default for its type. (V36) SYNOPSIS status = PutDefDiskObject(diskobj) BOOL PutDefDiskObject(struct DiskObject *); FUNCTION This routine writes out a DiskObject structure, and its associated information. If the call fails, FALSE will be returned. The reason for the failure may be obtained via IoErr(). Note that this function calls PutDiskObject() internally which means that this call (if sucessful) notifies workbench than an icon has been created/modified. Using this routine protects you from any future changes to the way default icons are stored within the system. INPUTS diskobj -- a pointer to a DiskObject RESULTS status -- TRUE if the call succeeded else FALSE SEE ALSO dos.library/IoErr icon.library/GetDefDiskObject icon.library/GetIconTagList icon.library/PutDiskObject icon.library/PutDiskObject icon.library/PutDiskObject NAME PutDiskObject - write out a DiskObject to disk. SYNOPSIS status = PutDiskObject(name, diskobj) BOOL PutDiskObject(STRPTR, struct DiskObject *); FUNCTION This routine writes out a DiskObject structure, and its associated information. The file name of the info file will be the name parameter with ".info" postpended to it. If the call fails, FALSE will be returned. The reason for the failure may be obtained via IoErr(). As of release V2.0, PutDiskObject() (if successful) notifies Workbench when an icon has been created/modified. Using this routine protects you from any future changes to the way icons are stored within the system. INPUTS name -- name of the object (pointer to a character string) diskobj -- a pointer to a DiskObject RESULTS status -- TRUE if the call succeeded else FALSE NOTES It is recommended that if you wish to copy an icon from one place to another than you use GetDiskObject() and PutDiskObject() and do not copy them directly. SEE ALSO dos.library/IoErr icon.library/DeleteDiskObject icon.library/FreeDiskObject icon.library/GetDiskObject icon.library/GetIconTagList icon.library/PutIconTagList icon.library/PutIconTagList icon.library/PutIconTagList NAME PutIconTagList -- Store an icon (V44) SYNOPSIS success = PutIconTagList(name,icon,tags); BOOL PutIconTagList(STRPTR name,struct DiskObject *icon, struct TagItem *tags); success = PutIconTags(name,icon,tag1,...); BOOL PutIconTags(STRPTR name,struct DiskObject *icon, Tag tag1,...); FUNCTION This function is used to store an icon; the icon can belong to a file/drawer/volume or it can be a default icon. INPUTS name -- Name of the object the icon is to be stored for, or NULL if a default icon is to be stored. icon -- The icon to be stored. tags -- Storage options. TAGS ICONPUTA_NotifyWorkbench (BOOL) -- Set this to TRUE to notify Workbench of the fact that an icon was changed. This tag defaults to FALSE. ICONPUTA_PutDefaultType (LONG) -- Type of the default icon this icon is to replace; must be one of WBDISK, WBDRAWER, WBTOOL, WBPROJECT, WBGARBAGE, WBDEVICE or WBKICK. If this tag is used, the "name" parameter will be ignored. ICONPUTA_PutDefaultName (STRPTR) -- Name of the default object type this icon is to be stored as. If this tag is used, the "name" parameter will be ignored. ICONPUTA_DropPlanarIconImage (BOOL) -- If you decide that the palette mapped icon imagery is sufficient to represent an icon, you can tell icon.library not to store the original, planar icon image data with the icon file. To do this, set this tag to TRUE. Instead of the planar icon images, a single default image will be stored. This can result in space savings but may not look too pretty. This tag defaults to FALSE. ICONPUTA_DropChunkyIconImage (BOOL) -- This tag can be used to keep the chunky icon image data from getting written to disk. This tag defaults to FALSE. ICONPUTA_DropNewIconToolTypes (BOOL) -- This tag controls whether any NewIcon tool types will be omitted when writing the icon to disk. TRUE will omit the data. This tag defaults to FALSE. ICONPUTA_OptimizeImageSpace (BOOL) -- A palette mapped icon image might not use the entire icon palette. By default, icon.library does not bother about this, it expects the creator of the icon to choose its palette efficiently. But just in case, you can tell icon.library to attempt to identify how many colours are really in use and to optimize its image compressor for them. This may take extra time and is not recommended for daily use. This tag defaults to FALSE. ICONPUTA_OnlyUpdatePosition (BOOL) -- This tag can be used to reduce the overhead in updating icon information on disk if the only information changed is the icon position. For this case, you can set this tag to TRUE. The icon to be modified will have only its do_CurrentX/do_CurrentY member values changed, the remainder will stay unmodified. Please note that this tag only takes effect if the ICONPUTA_PutDefaultType and ICONPUTA_PutDefaultName tags are omitted. This tag defaults to FALSE. ICONPUTA_PreserveOldIconImages (BOOL) -- Before writing a palette mapped icon back to disk, icon.library will make sure that the original planar image data is stored in the file. If you don't want that to happen, set this option to FALSE. This tag will allow you to change the planar icon image data written back to disk. This tag defaults to TRUE. ICONPUTA_FileFormat (STRPTR) -- Tell icon.library what file format the icon should be saved in, by passing the name of a file format which is supported by some external icon saver module. If the icon saver module for the requested file format can't be found, or if it fails to save the icon in that format, the icon will be saved in native Amiga format, unless you also specify ICONPUTA_NoFallback as TRUE. You can pass NULL to request the same format of the file the icon was originally loaded from, or ~0UL to explicitly request the native Amiga format. (V51) This tag defaults to NULL. ICONPUTA_NoFallback (BOOL) -- Tell icon.library to fail if the icon cannot be saved in the requested file format, rather than falling back to saving it in native Amiga format. This tag is ignored if the requested file format is the native Amiga format. (V51) This tag defaults to FALSE. ICONA_ErrorCode (LONG *) -- Pointer to a LONG word variable to store error codes in. Note that this variable will be initialized regardless of whether an error occured or not. Thus, you can check for an error condition by comparing the variable contents against 0; 0 indicates success, all other values are error codes as defined by dos.library. RESULT success -- TRUE if the icon file could be stored, FALSE otherwise. You can use IoErr() to retrieve the error code or use the ICONA_ErrorCode tag instead. EXAMPLE /* Store an icon as the default "picture" icon. */ struct DiskObject *icon; LONG errorCode; BOOL success; success = PutIconTags(NULL,icon, ICONPUTA_PutDefaultName,"picture", ICONA_ErrorCode,&errorCode, TAG_DONE); if(success == FALSE) { Printf("could not store default picture icon;\n"); PrintFault(errorCode,NULL); } NOTES This function is a superset of PutDefDiskObject() and PutDiskObject(). If the name of the icon file to be stored would be too long to fit (as set with IconControl(..., ICONCTRLA_SetGlobalMaxNameLength, ...)) then PutIconTagList() will silently pretend that the icon file has been written to disk. However, it will not store the icon file on the disk since there would a risk of accidentally overwriting the file the icon belongs to. If you want to know whether the icon you wrote was in fact written to disk, provide an error code pointer with the ICONA_ErrorCode tag. If the name of the file was too long, PutIconTagList() will still pretend that the icon file was written successfully, but the error code ERROR_TOO_MANY_LEVELS will be stored in the variable you passed in with the ICONA_ErrorCode tag. SEE ALSO workbench/icon.h workbench/workbench.h icon.library/GetIconTagList icon.library/PutDefDiskObject icon.library/PutDiskObject