AppWindow icon drop zones
=========================

Adding drop zones
-----------------

   Once it is created, Workbench will allow the user to drop an icon
anywhere inside an AppWindow, regardless of whether the icon was
dropped on an area designated for dropping icons on or not. With
AddAppWindowDropZoneA() you can tell Workbench which AppWindow areas
are suitable for dropping icons on.

Drop zone AppMessages
---------------------

   Once an AppWindow has a drop zone installed, Workbench will send a
new type of AppMessage to your port if icons are dropped on a drop
zone. Instead of AMTYPE_APPWINDOW type messages you will receive
AMTYPE_APPWINDOWZONE messages. In fact, you will no longer hear any
AMTYPE_APPWINDOW type messages since Workbench will allow users to drop
icons only on drop zones.  Be prepared to handle this.

   Adding a drop zone to an AppWindow does not guarantee that only
AMTYPE_APPWINDOWZONE type messages will arrive at your message port. In
fact, the user may be able to drop an icon on the window before the
first drop zone is installed. Be prepared to handle this.

Drop zones priority
-------------------

   Workbench checks drop zones in the order in which they were added to
the AppWindow. Thus, if two zones overlap, the zone that was added
first will be reported as hit.

   An AppWindow starts out with its entire area available for dropping
icons on. Thus, you may receive AppMessages for icons dropped upon your
AppWindow before you have added the first drop zone to it. Be prepared
to handle this.

Drop zone hooks
---------------

   Using the WBDZA_Hook tag, you can set a hook that will be invoked
whenever the mouse enters or leaves your drop zone area. Your hook will
be called with the following parameters:


     result = hookFunc(hook,reserved,arm)
       D0               A0     A2     A1

     LONG hookFunc(struct Hook *hook, APTR reserved,
                   struct AppWindowDropZoneMsg *adzm);

     struct AppWindowDropZoneMsg
     {
         struct RastPort * adzm_RastPort;    /* RastPort to render into. */
         struct IBox       adzm_DropZoneBox; /* Limit your rendering to this area. */
         ULONG             adzm_ID;          /* \ These come from straight */
         ULONG             adzm_UserData;    /* / from AddAppWindowDropZoneA(). */
         LONG              adzm_Action;      /* See below for a list of actions. */
     };

     #define ADZMACTION_Enter (0)
     #define ADZMACTION_Leave (1)


   The `reserved' parameter will be set to NULL.  For future
enhancement, make sure that your hook function always returns NULL.

   The drop zone message contents are as follows:

adzm_RastPort
     A pointer to the RastPort to render into. Typically, this is the
     RastPort of the window the drop zone is attached to.

adzm_DropZoneBox
     This member describes the position and size of the drop zone.  The
     zone is guaranteed to be a valid area, i.e. the Width and Height
     will both be greater than 0 and the Left/Top will be well within
     the bounds of the window containing the drop zone.

adzm_ID
adzm_UserData
     These two come straight from the values you passed as the `id' and
     `userData' parameters to AddAppWindowDropZoneA().

adzm_Action
     Depending upon whether the mouse has just entered or left the drop
     zone area, this variable will be set to ADZMACTION_Enter or to
     ADZMACTION_Leave. Any other values for adzm_Action should be
     ignored.

   When the mouse enters the drop zone, do your drop zone area
highlighting. When the mouse leaves the drop zone, remove any
highlighting done in the previous ADZMACTION_Enter pass.

   Note that the mouse leaving your drop zone box does not imply that
no icons will be dropped on it. You may still receive a notification
lateron, telling you that your drop zone had icons dropped on it.  The
hook function is solely for highlighting and unhighlighting the drop
zone area.

   A final word of warning: when your hook code is called, you must
limit your rendering to simple drawing operations from graphics.library;
if you do anything complex that involves Intuition locking and unlocking
the display, such as refreshing gadgets or locking IntuitionBase, you
will deadlock the operating system. You have been warned!

Removing drop zones
-------------------

   Use RemoveAppWindowDropZone() to remove a drop zone previously added
with AddAppWindowDropZone(). Due to the asynchronous nature of
Workbench/user interaction, you may receive AppIcon drop zone messages
for zones that you have just removed. These messages may arrive in the
time between your code calling RemoveAppWindowDropZone() and Workbench
responding to the drop zone removal request. Be prepared to handle
this. Once a drop zone is removed, it will generate no new AppMessages.

   Before the AppWindow is removed, all its drop zones will be removed
first. There is no need for you to call RemoveAppWindowDropZone() for
every single one.