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 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.


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