LayoutIconA

Adapt a palette-mapped icon for display (V44)

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

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 using dos.library/IoErr.

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.

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>