Go to the first, previous, next, last section, table of contents.

## 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 `AppMessage`s

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 `AppMessage`s 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 `AppMessage`s.

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.

Go to the first, previous, next, last section, table of contents.