Docs » Autodocs » icon.library » LayoutIconA
LayoutIconA -- Adapt a palette-mapped icon for display (V44)
success = LayoutIconA(icon,screen,tags);
D0 A0 A1 A2
BOOL LayoutIconA(struct DiskObject *icon,struct Screen *screen,
struct TagItem *tags);
success = LayoutIcon(icon,screen,...);
BOOL LayoutIcon(struct DiskObject *icon,struct Screen *screen,...);
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.
icon -- The icon to be remapped. This must be a palette mapped
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
tags -- Additional rendering options.
OBP_Precision (LONG) -- Pen colour allocation precision.
Default is the same precision as set in the global
icon.library settings (see IconControlA()).
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
You must make sure that the screen you remap to does notdos.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>
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.