OVERVIEW:

wIconCalls.c implements the programmer's interface to wIconify.  It allows
programs to specify their own, unique icon imagery for their windows; to
manipulate their icons in more complex ways; to obtain information about
icons and the wIconify system; and to maintain icons that do not have
windows associated with them.

wIconCalls should be compiled and linked with the program that uses the
wIconify programmer's interface (eventually, in the future, this will
become a shared library).  The interface uses message-passing to communicate
with the wIconify process.  The machinery for these messages is hidden in
the wIconCalls routines, so that the programmer will be virtually unaware
that it even exists.  Be aware, however, that any of the wIconCalls routines
may call the Wait() function (this may effect the Forbid() status, for example).


WICONCALLS STRUCTURES AND ROUTINES:

wIconCalls follows a strict naming convention to help prevent name conflicts
with the programs that use it.  Any global routine that is part of the
wIconCalls package starts with the letter 'w'; for example, wSetIcon() and
wIconOf().  The same goes for the structures and types defined by wIconCalls,
although if the types are defined in terms of C pre-processor macros, the
name will be in all upper-case letters, including the initial 'W'.
Finally, any macros defined in the wIconCalls hearder file all begin with 
'WI_' to help prevent conflicts with macro names (this is a practice that
more programs should get in the habit of doing).  There is one exception to
this rule, which is the macro BIT(n) which produced an integer with a 1 in
bit position  n  and zeros elsewhere (ie, it equals (1<<n)).

wIconCalls defines two major structures:  wIcon and wIconMessage.  These are
declared in the file wIcon.h, which should be included into any module that
will be using the wIconCalls interface.

The wIcon structure defines the setup for an icon (its imagery, flags,
etc.), and is used by wIconify to create an icon, but it is not the icon
itself; it is simply a template.  This is similar to the NewWindow structure
of Intuition; it is not the window itself, only the definition of one.
Intuition uses a NewWindow structure to create an actual Window structure.

In the same way, wIconify takes a wIcon template and creates an actual
icon.  The icon structure itself is for internal use by wIconify, and you are
not given the definition of this structure (it may change in the future
without notice).  When you create an icon, wIconify will give you an icon
reference pointer, which you use to refer to the icon when you call
wIconCalls routines.  wIcon.h declares a type WICONREF for these reference
pointers, and a type WICON that is equivalent to 'struct wIcon'.

For example, the following code fragment uses a static WICON structure to
add an icon to a window, iconifies the window, and then requests that the
icon be selected, deselcting any other selected icons.

    WICON MyIcon = { /* static definition of wIcon goes here */ };
    WICONREF *IconRef;
    struct Window *myWindow;

    /* create a window */
    IconRef = wSetIcon(myWindow,MyIcon);
    wIconify(myWindow);
    wSelectIcon(IconRef,FALSE);
 
Most icons will be associated with windows, as in the example above.  In
this case, wIconify maintains the icon itself and removes the icon
automatically when the window is closed.  At this point the WICONREF for
that icon will become invalid, and should NOT be used.  wIconify can not
tell an invalid WICONREF from a valid one (any more than Intuition can tell
a valie window pointer from an invalid one), so be sure not to use a WICONREF
after its window is closed.

There are times, however, when you may want to have an icon with no window
attached (as is the case for the wIconClock icon).  In this case, you have
to ask wIconify to create and delete the icon for you through the wAddIcon()
and wRemoveIcon() calls.  Be sure to remove every icon you add, or wIconify
will be left with icons that will never be removed.  This will prevent the
screens where they reside from being able to close.  As with window icons,
once the icon has been removed, the WICONREF becomes invalid and should not
be used.

The second structure defined in wIcon.h is the wIconMessage structure.  It
is used as a means of communication from wIconify to your program, and in
many ways is similar to IntuiMessages that Intuition sends to your windows. 
You can ask that wIconify let you know about important events in the lives
of your icons; for example, you can ask to be informed when an window
becomes iconified, or when an icon is openned or closed, or when your icon
becomes selected, or when it moves.  You can even find out about new screens
being openned, and other global events.  These message come to you as
wIconMessages and they are sent to you through the IconPort associated with
your icon.  This process is discussed in more detail below.


RECEIVING WICONMESSAGES:

One of the most powerful aspects of the wIconCalls interface is the wide
range messages that you can receive from wIconify concerning the icons you
set up.  These are described in the two previous sections.  To get any
wIconMessages, however, you must provide wIconify with an IconPort where it
can send the messages.  Each wIcon need not have its own port - you can use
the same port for all the icons you create.

You select what kinds of messages you want to receive by setting the
WI_REPORT flags for your icon.  Once your icon is attached to a window, or
added to a screen, you can use the Exec's Wait() function to wait for a
message from wIconify (a typical approach would be to Wait() for a message
either from wIconify or from Intuition).

Once you receive a message, be sure to reply to it.  If the user asks
wIconify to end (either through the END menu item or by issuing the wIconify
command while wIconify is running), wIconify will not be able to end until
all the wIconMessage it has sent out are returned to it.  If you fail to
reply to a message, wIconify will never end!

You should not modify the contents of a wIconMessage, except when
specifically instructed to, as in the WI_REPORTICONVERIFY message.
The wIconMessage structure is discussed in detail in the section THE
WICONMESSAGE STRUCTURE below.


ICONS WITHOUT WINDOWS:

Another important feature of the wIconCalls library is its ability to
provide icons that are not attached to any window.  For example, the
wIconClock utility uses just such an icon.  These windowless icons will
almost certainly require IconPorts, and it is for them that most of the
wIconMessage types will be most useful.  For example, the WI_REPORTOPEN and
WI_REPORTCLOSE calls are alsmost useless for icons with windows, but they
may be extremely important for windowless icons.  For example, programs that
modify the system, like DropCloth, could put a small icon on the Workbench
screen; openning this icon could bring up the program's configuration
requester.  Another example is wIconClock, which opens an icon on every
screen simply for display purposes.

You can use wIconify as a more direct part of your program's user
interface.  For instance, you could open a screen and ask wIconify to put up
an icon for each of the major functions of you program.  Clicking on an
icon would initiate its function.  In a sense, these icons would act as
gadgets, but with the ability to be rearranged, and with a slightly
different set of messages available for them.

When you add an icon to a window, wIconify will remove the icon
automatically when the window closes; however, if you place an icon on a
screen, you must be sure to delete it yourself.  wIconify will not allow a
screen to close as long as there are icons open on it.  There are a number
of message types that can help in this situation.  First, you can specify
the WI_AUTOREMOVE flag for an icon, which indicates that wIconify can remove
that icon automatically as a screen closes.  If you don't want to use this
flag, you should probably request WI_REPORTSCREENCLOSE messages.  In this
case, when the a program tries to close the screen, wIconify will inform you
so that you can remove the icon yourself.  Once all the icons are removed,
wIconify will let the screen close.  If you fail to remove your icon,
however, wIconify will never let the screen close!


SCREEN ICONS:

The screen icons are actually associated with the wIconify backdrop window
for each screen.  If you attempt to iconify this window, the screen will be
iconified.  If you request the pointer to the window associated to a screen
icon, you will get a pointer to the wIconify backdrop window.  Thus it is
possible to do all your icon work with just window pointers and never deal
with the screen-specific calls.  They are provided for your convenience,
however, and are usually just as easy to use; but you should be aware of
this somewhat unusual arrangement.
 

THE WICON STRUCTURE:

A wIcon has the following structure:

struct wIcon
{
   char *Name;
   struct Image *Image;
   struct Image *Select;
   UWORD *Mask;
   WORD x,y;
   ULONG Flags;
   ULONG Report;
   struct MsgPort *IconPort;
};

The fields are used as follows:


  Name

This is a pointer to the string to use for the name that appears just below
the icon.  If this field is NULL, then the wIconify will use the name of the
window associated with the icon (if there is no window for this icon, then 
the string '[no title]' will be used).  To have a blank name, this field
should point to an empty string.  The name will be centered under the icon.


  Image

This is a pointer to an Image structure that should be used for the icon's
image when it is unselected.  The size of the image can be up to 78 by 32
pixels, and can be as many bitplanes as the screen it should appear on.
If this field is left NULL, the default image will be used.  The default
image can be specified using the wIconify initialization file (the wIconify
documentation for more details).


  Select

This is a pointer to an Image structure that should be used for the icon's
image when it is selected.  In general, it should be the same size as the
one used for the Image.  If the field is left NULL, then an inverted version
of the Image is used, unless the image is the default image and a default
select image has been specified, in which case it is used instead.  You can
specify a default select image in the wIconify initialization file.


  Mask

This is a pointer to an array of UWORDS to use as a mask for the icon.  The
mask should be the same size as either the Image or the Select image, if one
is provided.  The mask is used when the icon is being dragged to a new
location.  Only the image bits that correspond to 1's in the mask will be
drawn while the icon is being moved.  The mask will also be used as a "hit
mask" for the image it is associated with; that is, mouse clicks will only
be counted if they are on a pixel that corresponds to a 1 bit in the mask.
If no Select image is provided, the mask is used as a hit mask for both the
Image and the Select image; if a Select image is provided, the mask is only
in effect when the Select image is being displayed.


  x,y

These fields give the initial position of the icon in pixels from the upper
left-hand corner of the screen.  If the icon would fall outside the visable
area of the screen, or would overlap some other icon, it will be moved to
the nearest open position on the screen, unless the WI_LOCKED flag is
specified.  If x and y are both 0, wIconify will place the icon at the first
available open position at the bottom of the screen.


  Flags

This field contains the flag bits that should be in effect for this icon. 
They can be chosen from among the following:
 
    WI_CHANGEREFRESH    If this icon's window is a SMART_REFRESH window,
                        change it to SIMPLE_REFRESH when iconified (this flag
                        has no effect on screen icons)

    WI_LOCKED           Never change the location of this icon, no matter what

    WI_NOMOVE           The user can not drag this icon

    WI_NOORGANIZE       The CLEANUP or ORGANIZE menus won't move this icon

    WI_NOSAVEPOS        Don't remember the icon's position after it is openned,
                        it will be placed at the first available location next
                        time it is iconified

    WI_NOMULTISELECT    Don't allow any other icons selected when this one is

    WI_NOCLOSE          The CLOSE menu will not be available for this icon
                        (this flag has no effect on screen icons)

    WI_NOICONIFY        Don't allow this icon's window to become iconified

    WI_AUTOREMOVE       Remove this icon automatically when the screen it
                        is on closes (for icons with no windows attached)

The following flags, which determine where the icon will appear and which
direction to look for an open position, are not yet implemented.  They appear
here for future compatibility.

    WI_LTOP
    WI_LBOTTOM
    WI_RTOP
    WI_RBOTTOM
    WI_VERTICAL
    WI_HORIZONTAL


In addition to the flags set by the user, wIconify maintains the following
two flags:

    WI_ICONIFIED        This icon is currently iconified

    WI_SELECTED         This icon is currently selected


It is important to understand the difference between WI_LOCKED and WI_NOMOVE.
WI_NOMOVE simply means that the user can not drag the icon; wIconify is
still free to position the icon as it sees fit in order to make the screen
as uncluttered as necessary (for example, it is allowed to move the icon if
some other icon is already at the location it requests).  On the other hand,
WI_LOCKED indicates that wIconify may not move the icon under any
circumstances, and that the icon's x,y position is exactly what it should be.
This means that even if some other icon is in the way, or even if the icon
will appear off the edge of the screen, wIconify will not move it, and a
position of 0,0 will not be turned into the first open position.  Of course,
wIconify will still allow you to move the icon via calls to wMoveIcon().

The combination of WI_NOMOVE and WI_NOORGANIZE is nearly the same as
WI_LOCKED, except that it give wIconify the option of resolving the
icon-overlap and off-screen problems without letting the icon be moved
around by the user, but WI_LOCKED is still available if you really want to
prevent this.

If you specify the WI_CHANGEREFRESH flag, the icon's window will be converted
to a SIMPLE_REFRESH window before it is sent to the back.  Be aware,
however, that this means any data displayed in the window will be lost! 
When the window becomes visible again, Intuition will refresh its frame, but
you will have to redraw the contents of the window yourself.  You may need
to request WI_REPORTRESTORE messages in order to accomplish this.  In this
case, though, you might as well have used a SIMPLE_REFRESH window in the
first place.  Use of the WI_CHANGEREFRESH flag is not recommended, but is
available if you want to try to save memory.


  Report

This field specifies what type of wIconMessages you want to receive
for this icon.  The messages come via the IconPort field described below,
and can be chosen from the following flags:
 
  WI_REPORTICONIFIED    Report when this icon's window is iconified

  WI_REPORTRESTORE      Report when this icon is restored (the icon is
                        reomved frlom the screen and its window openned)

  WI_REPORTICONVERIFY   Don't iconify the window until this message is
                        replied (see below for more details)

  WI_REPORTMOVED        Report when the icon is moved to a new location
                        by the user

  WI_REPORTSELECT       Report when this icon becomes selected

  WI_REPORTUNSELECT     Report when this icon becomes unselected

  WI_REPORTPRESS        Report when this icon is clicked on by the mouse
                        (this is different from WI_REPORTSELECT; see below)

  WI_REPORTRELEASE      Report when this icon is released after is has been
                        pressed (for example, when it has been dragged to a
                        new location)

  WI_REPORTOPEN         Report when the user double-clicks this icon or chooses
                        the OPEN menu when it is selected.  This is for use
                        mainly with icons that have no windows attached; see
                        below.

  WI_REPORTCLOSE        Report when the user attempts to close this icon.
                        This is for use mainly with icons that have no windows
                        attached; see below.

  WI_REPORTAUTOREMOVE   Report when this icon is removed automatically by
                        wIconify when its screen closes.

In addition to these reports that pertain to a specific icon, you can get
messages about more global aspects of wIconify:

  WI_REPORTNEWSCREEN    Tell me when new screens appear.  This is for use
                        with programs like wIconClock that want to put
                        icons on every screen.

  WI_REPORTSCREENCLOSE  Tell me when the screen is trying to close.  This
                        is to let icons that are not WI_AUTOREMOVE icons
                        that it is time to get off this screen!

  WI_REPORTACTIVATE     Tell me when the wIconify window becomes active

  WI_REPORTINACTIVE     Tell me when the wIconify window becomes inactive

  WI_REPORTICONEND      Tell me when wIconify is trying to end.

There is one unimplemented flag, for future expansion:

  WI_REPORTDROP         Tell me when an icon is dropped on top of this one.
                        (This is to implement things like the trash-can and
                        drawer icons).

Note the difference between WI_REPORTRESTORE and WI_REPORTOPEN.  The former
is a message indicating that the icon's window has been successfully
restored and the icon removed from the screen.  The latter is a message that
the user wants the icon to open, but wIconify is leaving the details up to
you.  For example, wIconClock uses this message to switch between its
different display modes. 

WI_REPORTRESTORE is only applicable to icons with attached windows, and the
latter is mainly for icons without windows.  If an icon was the
WI_REPORTOPEN flag set, wIconify will generate a WI_REPORTOPEN message
whenever an attempt is made to restore the icon, including during a call to
the wRestore() routine.  If you wish to do some processing before your
window opens and you specify the WI_REPORTOPEN flag, when the message is
received, do whatever you need to do, then be sure to change the report
flags with wModifyReport() to remove WI_REPORTOPEN before you call wRestore()
for the window.  If you don't do this, you will just get another
WI_REPORTOPEN message and the window still won't be restored.  Usually, it
is better just to use WI_REPORTRESTORE and do whatever you need to do then.

If you specify the WI_REPORTICONVERIFY flag, then when the user tries to
iconify the window associated with your icon, you will receive the icon
verify message.  wIconify will wait for you to reply to the message before
it iconfies the window, giving you a chance for you to do whatever you need
to do to the window to prepare it for iconification.  If everything is OK
and you want to allow the window to become iconified, set the WI_ICONIFYOK
flag in the wIconMessage Flags field.  If you decide that the window should
NOT become iconified, clear this flag in the wIconMessage Flags field.  You
must reply to the message in either case.

The distinction between WI_REPORTSELECT and WI_REPORTPRESS also is
important.  The WI_REPORTSELECT message indicates that the icon has become
selected.  This can happen in a number of ways:  the user can click it, it's
window can become iconified, which usually selects the newly-created icon,
or your program can call wSelectIcon to select it.  On the other hand,
WI_REPORTPRESS indicates the the user has clicked the mouse over the icon. 
This message will be reported even if the icon is already selected.

The WI_REPORTACTIVATE and WI_REPORTINACTIVE messages apply only to the
wIconify backdrop window where the icon exits, not to all wIconify windows;
that is, an icon will receive these messages only when it's backdrop window
becomes active or inactive.  Similarly, the WI_REPORTSCREENCLOSE message only
applies to the screen on which the icon is to be found.


  IconPort

This is a pointer to a MsgPort (message port) that wIconify should use to
send you the wIconMessages you have requested by the Report flags.  If the
port is NULL, wIconify will not send you any messages regardless of the
settings of the Report field.  An IconPort can be shared among many icons,
so there is no need to make an individual port for each icon you create.

 
THE WICONMESSAGE STRUCTURE:

The wIconMessage structure is used in two different ways:  first, it is the
means by which wIconify communicates with your program (through the
IconPorts of your icons), and second, it is the way the wIconCalls library
communicates with wIconify, through a named message port.  Much of the
wIconMessage structure is for use by the wIconCalls library, and will not be
used directly by you, nor with that portion of the structure be explained here.
When you receive a wIconMessage, you should not modify any of its fields,
except as specifically instructed, nor should you rely on the contents of the
Data field, which is not valid when part of messages from wIconify to you.

The wIconMessage structure is as follows:

struct wIconMessage
{
   struct Message Message;
   struct Window *Window;
   WICONREF *Icon;
   ULONG Action;
   ULONG Flags;
   union
   {
      struct Window *Window;
      struct Screen *Screen;
      WSCREEN *wScreen;
      struct {WORD x,y;} Position;
      struct {UWORD Depth,Modes;} NewScreen;
      struct {UWORD Maj,Min;} Version;
      struct {UWORD ScreenType,SizeToFit;} OpenOn;
      WICON *Icon;
      APTR DataPtr;
   } Data;
};

The fields have the following meanings:


  Message

This is an Exec Message structure that is used to link the message into the
IconPort, and includes the information necessary for you to be able to reply
to the message.  You should not need to use this field yourself.


  Window

This is a pointer to the window associated with the icon.


  Icon

This is a pointer to the icon which is being affected by the message (in
case you are using a common IconPort for all your icons).  Note that this
a is pointer to a WICONREF, not a pointer to a wIcon.


  Action

This tells you what type of event you have received.  It will be one of the
WI_REPORT flags described above.  [This field also has special values when
used as a message directed to wIconify by the wIconCalls library; see the
wIcon.h include file for a list of these values.]


  Flags

This field is used by wIconify to maintain information about the message. 
The only value of interest to icon reports is WI_ICONIFYOK.  If you
receive a WI_REPORTICONVERIFY message, you must set or clear this flag
depending on whether you want wIconify to go ahead any iconify the window in
question.  If the window should be iconified, set the flag, otherwise clear
it.  Be sure that you do not alter the values of the other flags, as they
are used by wIconify and the wIconCalls library.  [There are anumber of
additional flags for internal use only; they are listed in the wIcon.h file.]

  union Data

This field is for internal use only, and should not be altered or used in
any way by your program.  The values are all initialized and maintained by
the wIconCalls library.

 
WICONCALLS ROUTINES:

The routines below are part of the file wIconCalls.c which you should
compile and link with your programs that want to use the wIconify
programmer's interface.  Each of thr routines listed here indicates the type
of its return value and the types of each of its arguments.  In most cases,
NULL pointers will not cause a problem (wIconify will simply ignore the
call, or provide a default when appropriate), so it's OK to use
constructions like wIconify(wWindowOf(myIcon)) even though wWindowOf() may
return NULL; the wIconify() routine is smart enough to check that the window
pointer it gets is non-NULL.

The wIconCalls library communicates via wIconMessages with the wIconify
handler process itself.  Since the wIconify process can end at any time (by
the user selecting the END menu item, for example), this can be a tricky
business.  For example, wIconify can be ended and restarted between two
calls by your program to the wIconCalls library, and this would invalidate
all your WICONREF pointers!  

In order to overcome at least some of the problems presented by this type of
communication, wIconCalls checks to see that the same wIconify is running
each time you make a call to the wIconCalls library.  If wIconify is no
longer running, or if a different copy of it is running, then all subsequent
calls to the wIconCalls library will return NULL or 0 values.

The wIconCalls library also checks the version of wIconify when it first
makes contact.  Both wIconCalls and wIconify must agree that their versions
match before any additional communication will be allowed.  If the versions
don't match, all further calls to the wIconCalls library will return NULL
or 0 values.

The routines available in the wIconCalls library are the following:


int wIconifyActive()

This routine checks to see if wIconify is currently running.  It returns
TRUE if wIconify is active and of a compatible version, and FALSE otherwise.
You can use this routine to check to see whether your program should try to
add icons to its windows, etc.

 
WICONREF *wIconify(theWindow)
struct Window *theWindow;

This routine attempts to iconify the specified window.  If successful, it
will return the WICONREF for the icon of that window (wIconify will create
one if the window does not already have one), and will return NULL
otherwise.  The icon will appear on the same screen as the window, and will
be selected if the window was the active one.


WICONREF *wIconifyScreen(theScreen)
struct Screen *theScreen;

This routine attempts to iconify the given screen.  If successful, it will
return the WICONREF of the scren's icon, and will return NULL otherwise.
The icon will appear on the Workbench screen, and will be selected if the
active window was on the specified screen.


void wRestore(theIcon)
WICONREF *theIcon;

This routine attempts to restore the window of an iconfied icon.  The window
will be brought to the front and activated, and the icon will be removed
from the screen (but will still be associated with the window).  Calling
this routine has the same effect as the user selecting the icon an choosing
OPEN from the ICON menu.


WICONREF *wSetIcon(theWindow,theIcon)
struct Window *theWindow;
WICON *theIcon;

This routine associates an icon with a window.  If successful, the routine
will return a WICONREF pointer, and if unsuccessful (e.g., not enough
memory) will return NULL.  The WICONREF pointer is what you will need to use
to refer to the icon in most of the remaining wIconCalls routines.  The
WICON itself is only a template used by wSetIcon() to create the WICONREF
itself; any changes you make to theIcon after the call to wSetIcon will not
affect the window's icon.

This routine DOES NOT iconify the window; it only associates the icon with
the window so that when the window is iconified, it will have the right
imagery, flags, position, etc.  If the window alreay has an icon, this
routine will update the values of the existing icon.


WICONREF *wSetScreenIcon(theScreen,theIcon)
struct Screen *theScreen;
WICON *theIcon;

This routine associates an icon with a screen.  If successful, it will
return a WICONREF pointer, otherwise it returns NULL.  See wSetIcon() above
form more details about WICONREFs and creating icons.


void wUnSetIcon(theWindow)
struct Window *theWindow;

This removes the icon associated with a window.  If the window is iconified
in the future, wIconify will create a new icon for it, and will give it the
default icon imagery and flags.  If the window has no icon, this routine
has no effect.  If the window is iconified, it will be restored first.


void wUnSetScreenIcon(theScreen)
struct Screen *theScreen;

This removes the icon associated with a screen.  If the screen is iconified
in the future, wIconify will create a new icon for it, and will give it the
default icon imagery and flags.  If the screen has no icon, this routine
has no effect.  If the screen is iconified, it will be restored first.


void wUpdateIcon(theIcon,WIcon)
WICONREF *theIcon;
WICON *WIcon;

This routine updates the values of the WICONREF to those specified in the
wIcon.  This is equivalent to unsetting the icon then setting it again.
This routine is especially useful when used in conjunction with
wGetIconData().


void wGetIconData(theIcon,theIconRef)
WICON *theIcon;
WICONREF *theIconRef;

This routine copies the data from the WICONREF into the wIcon structure. 
This gives you a "snap shot" of the current status of the icon.  You can use
this in conjuntion with wUpdateIcon() to modify an icon's values.


void wIconXY(theIcon,X,Y)
WICONREF *theIcon;
WORD *X,*Y;

This routine sets the X and Y variables to the current location (in pixels
from the upper left-hand corner of the screen) of the specified icon.  You
can modify the icon's location using the wMoveIcon() routine.


ULONG wIconFlags(theIcon)
WICONREF *theIcon;

This routine returns the current settings of the Icon's Flags field.  This
can be used to check the WI_SELECTED or WI_ICONIFIED flags, for instance. 
Use the wModifyFlags() routie to change the settings of the user-assigned
flags.

ULONG wIconReport(theIcon)
WICONREF *theIcon;

This routine returns the current settings of the icon's Report flags.
Use wModifyReport() to change the flags.


void wModifyFlags(theIcon,Flags)
WICONREF *theIcon;
ULONG Flags;

This routine sets the icon's Flags field to the given flags.  Only the user-
assignable flags will be modified; any system flags will remain unchanged
regardless of their presence or absence in the Flags parameter.  Use
wIconFlags() to retrieve the current settings of the flags.


void wModifyReport(theIcon,Report)
WICONREF *theIcon;
ULONG Report;

This routine sets the icon's Report flags to the requested values.  Use
wIconREport() to retrieve the current settings of the Report flags.


void wMoveIcon(theIcon,x,y)
WICONREF *theIcon;
WORD x,y;

Thie routine moves the specified icon to the specified location.  The x
and y values represent pixels from the upper left-hand corner of the screen.
Use wIconXY() to find the current location of the icon.


void wSelectIcon(theIcon,AddToSelect)
WICONREF *theIcon;
long AddToSelect;

This routine attempts to select the given icon.  If AddToSelect is TRUE,
then it will be added to the current list of selected icons; if AddToSelect
is FALSE, then any selected icons will become unselected first.


void wUnSelectIcon(theIcon)
WICONREF *theIcon;

This routine unselects the specified icon.  If it was not selected, then
this routine will have no effect.


WICONREF *wAddIcon(theScreen,theIcon)
struct Screen *theScreen;
WICON *theIcon;

This routine attempts to add an icon without an associated window to the given
screen.  If successful, it returns a WICONREF pointer to the newly-created
icon, otherwise it returns NULL.  Since this icon will not have a window,
wIconify will not be able to take any action when the icon is doubel
clicked, or openned or closed; you should provide these icons with IconPorts
so that wIconify can inform you of these events so that your program can
take appropriate action.  See ICONS WITHOUT WINDOWS above for information
about icons with no associated windows.


void wRemoveIcon(theIcon)
WICONREF *theIcon;

This routine removes an icon created by wAddIcon().  You must be sure to
remove any icons that you add to a screen, otherwise the screen will not be
able to close.  See ICONS WITHOUT WINDOWS above for more information.


void wCloseIcon(theIcon)
WICONREF *theIcon;

This routine attempts to close the given icon.  This may send a CLOSEWINDOW
message to its associated window, or may send a WI_REPORTCLOSE message to
the icon.  If the icon haas the WI_NOCLOSE flag set, this routine will have
no effect.  Calling this routine is the same as the user selecting the icon
and choosing the CLOSE item from the ICON menu.


void wRefreshIcon(theIcon)
WICONREF *theIcon;

This causes the given icon to be redrawn (actually, all the icons on the
icon's screen will be redrawn).


void wNoIconify(theWindow)
struct Window *theWindow;

This routine marks a window as being un-iconifiable.  Any attempt to iconify
the window will fail.  To make the window iconifyable again, you must call
the wUnSetIcon() routine.


int wIsIconified(theWindow)
struct Window *theWindow;

This routine checks to see if a given window is currently iconified.  It
returns TRUE if it is iconified, and FALSE of not.


int wIsScreenIconified(theScreen)
struct Screen *theScreen;

This routine checks to see if a given screen is currently iconified.  It
returns TRUE if it is iconified, and FALSE if not.


WICONREF *wIconOf(theWindow)
struct Window *theWindow;

This routine returns the WICONREF pointer for the icon associated with the
given window.  If the window has no icon, it returns NULL.


WICONREF *wIconOfScreen(theScreen)
struct Screen *theScreen;

This routine returns the WICONREF pointer for the icon associated with the
given screen.  All screens are given default icon definitions when they are
openned, so it will return NULL only if the screen is one of the ones marked
to be ignored (via the IGNORE_SCREEN command of the wIconify initialization
file; see the wIconify documentation for more details).


struct Window *wWindowOf(theIcon)
WICONREF *theIcon;

This routine returns a pointer to the window associated with the given
icon.  If the icon has no window, it returns NULL.  If the icon is a screen
icon, it returns a pointer to the wIconify backdrop window for that screen.


struct Window *wBackDropOf(theScreen)
struct Screen *theScreen;

This routine returns a pointer to the wiconify backdrop window of the given
screen.  If the screen is one that wIconify is ignoring, this will return
NULL.  You should not really be messing with the backdrop window, but
sometimes you may need to find something out about its size or fonts, or
something.  You should not draw into this window yourself, or add gadgets or
other imagery to it.


THE FUTURE OF WICONCALLS:

Currently, wIconCalls is a single C source file that has to be linked into
your programs directly.  It might be helpful to turn it into a shared
library, just like Intuition.library, Graphics.library, etc.  The wIconCalls
file is pretty small, though, so maybe this is not so important.  It will
depend on the amount of demand there is for this feature.

There are a number of potential improvements for the interface, including
some of the unimplemented flags discussed above.  In addition, it would be
possible to allow programs to incorporate their own menus into the wIconify
backdrop window's menu bar.  It might also be useful to allow programs to
request that their own windows become icon windows (i.e, scrollable windows
that contain icons, just like the Workbench disk and draw windows).  This
would allow programs to take more advantage of the capabilities of the icon
interface of wIconify.  Of course, unless there is some demand from the
users of the wIconify programmer's interface, these things probably will
never happen.


AUTHOR:

wIconCalls
Copyright (c) 1990,1991 by Davide P. Cervone, all rights reserved.

Davide P. Cervone
Department of Mathematics
Brown University
Providence, Rhode Island  02912
ST402523@BROWNVM.BITNET
st402523@brownvm.brown.edu