icon.library Reference¶

Comprehensive function reference for icon.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/icon).

This page documents 24 functions of icon.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index¶

AddFreeList()
BumpRevision()
BumpRevisionLength()
ChangeToSelectedIconColor()
DeleteDiskObject()
DrawIconStateA()
DupDiskObjectA()
FindToolType()
FreeAlloc()
FreeDiskObject()
FreeFree()
FreeFreeList()
GetDefDiskObject()
GetDiskObject()
GetDiskObjectNew()
GetIconRectangleA()
GetIconTagList()
IconControlA()
LayoutIconA()
MatchToolValue()
NewDiskObject()
PutDefDiskObject()
PutDiskObject()
PutIconTagList()

`AddFreeList()`¶

AddFreeList - add memory to a free list.

Synopsis

status = AddFreeList(free, mem, len) D0 A0 A1 A2

BOOL AddFreeList(struct FreeList*, APTR, ULONG);

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

free -- 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;

`BumpRevision()`¶

BumpRevision - reformat a name for a second copy.

Synopsis

result = BumpRevision(newbuf, oldname) D0 A0 A1

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"

`BumpRevisionLength()`¶

BumpRevisionLength - length-limited name-reformatting for a copy (V45)

Synopsis

result = BumpRevisionLength(newbuf, oldname, length) D0 A0 A1 D0

STRPTR BumpRevisionLength(STRPTR, STRPTR, ULONG length);

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 given maximal file size. In case it cannot fit the fill the name even by truncation, it will return NULL.

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, or NULL in case the buffer is too small even for a truncated copy.

Example

`ChangeToSelectedIconColor()`¶

ChangeToSelectedIconColor -- Modify an RGB colour value for use in a selected icon image (V44)

Synopsis

ChangeToSelectedIconColor(cr) A0

VOID ChangeToSelectedIconColor(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.

`DeleteDiskObject()`¶

DeleteDiskObject - Delete a Workbench disk object from disk. (V37)

Synopsis

result = DeleteDiskObject(name) D0 A0

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...*\
}

`DrawIconStateA()`¶

DrawIconStateA -- Draw an icon as if it were an image (V44)

Synopsis

DrawIconStateA(rp,icon,label,leftEdge,topEdge,state,tags) A0 A1 A2 D0 D1 D2 A3

VOID DrawIconStateA(RastPort*rp,struct DiskObject*icon, STRPTR label,LONG leftEdge,LONG topEdge, ULONG state,TagItem*tags);

DrawIconState(rp,icon,label,leftEdge,topEdge,state,...);

VOID DrawIconState(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

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);

`DupDiskObjectA()`¶

DupDiskObjectA -- Duplicate an icon (V44)

Synopsis

icon = DupDiskObjectA(icon,tags); D0 A0 A1

struct DiskObject* DupDiskObjectA(struct DiskObject*icon, 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.

Results

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

IoErr(), GetIconTagList()

`FindToolType()`¶

FindToolType - find the value of a ToolType variable.

Synopsis

value = FindToolType(toolTypeArray, typeName) D0 A0 A1

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.

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.

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

See also

MatchToolValue()

`FreeAlloc()`¶

FreeAlloc - allocate memory and add it to a free list (V36).

Synopsis

memory = FreeAlloc( free, len, type ) D0 A0 A1 A2

APTR FreeAlloc(struct FreeList*, ULONG, ULONG);

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

free -- 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.

`FreeDiskObject()`¶

FreeDiskObject - free all memory in a Workbench disk object.

Synopsis

FreeDiskObject(diskobj) A0

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.

`FreeFree()`¶

FreeFree - free memory tracked by a free list (V44).

Synopsis

found = FreeFree( free, memory ) A0 A1

BOOL FreeFree(struct FreeList*, APTR);

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 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...

`FreeFreeList()`¶

FreeFreeList - free all memory in a free list.

Synopsis

FreeFreeList(free) A0

void FreeFreeList(struct 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

free -- a pointer to a FreeList structure; as of V44 a NULL free parameter will be ignored.

`GetDefDiskObject()`¶

GetDefDiskObject - read default wb disk object from disk. (V36)

Synopsis

diskobj = GetDefDiskObject(def_type) D0 D0

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.

`GetDiskObject()`¶

GetDiskObject - read in a Workbench disk object from disk.

Synopsis

diskobj = GetDiskObject(name) D0 A0

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

`GetDiskObjectNew()`¶

GetDiskObjectNew - read in a Workbench disk object from disk. (V36)

Synopsis

diskobj = GetDiskObjectNew(name) D0 A0

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

`GetIconRectangleA()`¶

GetIconRectangleA -- Query the size of the area an icon renders into (V44)

Synopsis

success = GetIconRectangleA(rp,icon,label,rectangle,tags) D0 A0 A1 A2 A3 A4

BOOL GetIconRectangleA(RastPort*rp,struct DiskObject*icon, STRPTR label,Rectangle*rectangle, TagItem*tags);

success = GetIconRectangle(rp,icon,label,rectangle,...);

BOOL GetIconRectangle(RastPort*rp,struct DiskObject*icon, STRPTR label,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.

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).

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.

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);
}

See also

IconControlA(), LayoutIconA()

`GetIconTagList()`¶

GetIconTagList -- Retrieve an icon (V44)

Synopsis

icon = GetIconTagList(name,tags); D0 A0 A1

struct DiskObject* GetIconTagList(STRPTR name,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.

Results

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

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.

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");
}

`IconControlA()`¶

IconControlA -- Set and get icon and icon.library options (V44)

Synopsis

processed = IconControlA(icon,tags); D0 A0 A1

ULONG IconControlA(struct DiskObject*,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.

Results

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.

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);".

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);
}

`LayoutIconA()`¶

LayoutIconA -- Adapt a palette-mapped icon for display (V44)

Synopsis

success = LayoutIconA(icon,screen,tags); D0 A0 A1 A2

BOOL LayoutIconA(struct DiskObject*icon,Screen*screen, TagItem*tags);

success = LayoutIcon(icon,screen,...);

BOOL LayoutIcon(struct DiskObject*icon,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). tags -- Additional rendering options.

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.

`MatchToolValue()`¶

MatchToolValue - check a tool type variable for a particular value.

Synopsis

result = MatchToolValue(typeString, value) D0 A0 A1

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.

Notes

icon.library V44 skips blank spaces surrounding the typeString options and the value string. Older icon.library versions did not support this.

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

See also

FindToolType(), Stricmp()

`NewDiskObject()`¶

NewDiskObject -- Create an empty icon (V44)

Synopsis

icon = NewDiskObject(type) D0 D0

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.

Results

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

IoErr()

`PutDefDiskObject()`¶

PutDefDiskObject - write disk object as the default for its type. (V36)

Synopsis

status = PutDefDiskObject(diskobj) D0 A0

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

`PutDiskObject()`¶

PutDiskObject - write out a DiskObject to disk.

Synopsis

status = PutDiskObject(name, diskobj) D0 A0 A1

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.

`PutIconTagList()`¶

PutIconTagList -- Store an icon (V44)

Synopsis

success = PutIconTagList(name,icon,tags); D0 A0 A1 A2

BOOL PutIconTagList(STRPTR name,struct DiskObject*icon, 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.

Results

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.

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.

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);
}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

icon.library Reference¶

Function index¶

AddFreeList()¶

BumpRevision()¶

BumpRevisionLength()¶

ChangeToSelectedIconColor()¶

DeleteDiskObject()¶

DrawIconStateA()¶

DupDiskObjectA()¶

FindToolType()¶

FreeAlloc()¶

FreeDiskObject()¶

FreeFree()¶

FreeFreeList()¶

GetDefDiskObject()¶

GetDiskObject()¶

GetDiskObjectNew()¶

GetIconRectangleA()¶

GetIconTagList()¶

IconControlA()¶

LayoutIconA()¶

MatchToolValue()¶

NewDiskObject()¶

PutDefDiskObject()¶

PutDiskObject()¶

PutIconTagList()¶

`AddFreeList()`¶

`BumpRevision()`¶

`BumpRevisionLength()`¶

`ChangeToSelectedIconColor()`¶

`DeleteDiskObject()`¶

`DrawIconStateA()`¶

`DupDiskObjectA()`¶

`FindToolType()`¶

`FreeAlloc()`¶

`FreeDiskObject()`¶

`FreeFree()`¶

`FreeFreeList()`¶

`GetDefDiskObject()`¶

`GetDiskObject()`¶

`GetDiskObjectNew()`¶

`GetIconRectangleA()`¶

`GetIconTagList()`¶

`IconControlA()`¶

`LayoutIconA()`¶

`MatchToolValue()`¶

`NewDiskObject()`¶

`PutDefDiskObject()`¶

`PutDiskObject()`¶

`PutIconTagList()`¶