LayoutIconA

Adapt a palette-mapped icon for display

Declaration

Source position: icon.pas line 372

Arguments

Function result

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

Description

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.

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 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 LayoutIconA() with a nil 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")).

See also