Autodocs
Libraries:
icon.library
AddFreeList
BumpRevision
ChangeToSelectedIconColor
DeleteDiskObject
DrawIconStateA
DupDiskObjectA
FindToolType
FreeDiskObject
FreeFreeList
GetDefDiskObject
GetDiskObject
GetDiskObjectNew
GetIconRectangleA
GetIconTagList
IconControlA
LayoutIconA
MatchToolValue
NewDiskObject
PutDefDiskObject
PutDiskObject
PutIconTagList
Include
GuruMeditation
|
Docs » Autodocs » icon.library » GetIconTagList
GetIconTagList -- Retrieve an icon (V44)
icon = GetIconTagList(name,tags);
D0 A0 A1
struct DiskObject * GetIconTagList(STRPTR name,struct TagItem *tags);
icon = GetIconTags(name,tag1,...);
struct DiskObject * GetIconTags(STRPTR name,Tag tag1,...);
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.
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.
/* 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");
}
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()
|
