Drawing icons in applications
=============================

DrawIconStateA()
----------------

   The V44 icon.library provides functions to support applications
which need to display icons in their own GUI. These include icon
editors, WBInfo() patches and full Workbench replacements. The pre-V44
method to draw an icon inside a window was to manipulate the images
embedded into the icon directly. As of V44, this technique is strongly
discouraged.

   The new icon.library/DrawIconStateA() function provides the same
functionality in a straightforward way. Shall the icon appearance be
changed with future extensions of the icon.library, your application
will pick them up automatically.

LayoutIconA()
-------------

   The icon.library supports drawing icons on any screen (not just on
the Workbench screen). For these reason, icon imagery can be loaded into
memory and then remapped at a later time by calling LayoutIconA().

   LayoutIconA() is called implicitly by GetIconTagList() (1). The
icons are automatically remapped for display on the screen selected
using IconControlA().  This could be undesiderable when your
application wants to display the icon on another screen.

   Note that LayoutIconA() allocates shared pens from the passed screen
using the graphics.library/ObtainBestPen() function.  These pens will
be released when the icon is disposed (with FreeDiskObject()) or when
the icon is remapped again by LayoutIcon(). It is VERY IMPORTANT that
your custom or public screen is not closed until there are still icon
objects remapped for it. See the LayoutIconA() AutoDoc for possible
workarounds.

   ---------- Footnotes ----------

   (1) To prevent this from happening, you must explicitly set the
ICONGETA_RemapIcon tag to FALSE.