GetIconTagList

Retrieve an icon (V44)

This function is used to retrieve an icon; the icon can belong to a file/drawer/volume or it can be a default icon.

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.

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.

Take care when doing this as the icon returned to you will have NULL pointers in the do_Gadget.GadgetRender and do_Gadget.SelectRender members.

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, this keeps the icon from getting remapped in the first place (see ICONGETA_RemapIcon for the consequences).

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.

ICONGETA_IdentifyBuffer (STRPTR)

Request the type of the actual file whose icon is being loaded by GetIconTagList(), as determined by the global identification hook. If this tag is passed, the file is identified even if it has a real icon. The value of this tag must be a pointer to a text buffer of at least 256 bytes, or NULL (which is ignored).

This tag only works with actual files (tools and projects), not volumes, directories or trashcans.

If the file cannot get identified, the supplied buffer will contain an empty string (a single NUL byte) on the function's return. (V47)

This tag defaults to NULL.

ICONGETA_IdentifyOnly (BOOL)

When using ICONGETA_IdentifyBuffer, you can ask not to actually load an icon, but just identify the file with the specified name (which is quicker if all you need is the file type, and doesn't require you to free an icon afterwards). If you pass this tag with a TRUE value, GetIconTagList() will return NULL with a zero error code in ICONA_ErrorCode.

Note:

this tag will be ignored if a valid buffer is not also

passed with ICONGETA_IdentifyBuffer. (V47)

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.

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.

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.

<workbench/icon.h>, <workbench/workbench.h>, icon.library/GetDiskObject(), icon.library/GetDiskObjectNew(), icon.library/GetDefDiskObject(), icon.library/IconControlA(), icon.library/PutIconTagList()