AddAppWindowDropZoneA

Designate an AppWindow area as suitable for dropping icons on. (V44)

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.

aw

An AppWindow data structure, as returned by workbench.library/AddAppWindowA.

id

This variable is strictly for your own use and is ignored by Workbench. Typical uses in C are in switch and case statements, and in assembly language table lookup. Later, when an icon is dropped on the designated area, the AppMessage sent to your port will have the am_ID member set to this value.

userData

this variable is strictly for your own use and is ignored by Workbench. Later, when an icon is dropped on the designated area, the AppMessage sent to your port will have the am_UserData member set to this value.

tags

List of attributes to control the position and size of the drop zone.

WBDZA_Left (WORD)

Left edge of the drop zone; a value of 0 would create a zone located at the left corner of the window.

WBDZA_RelRight (WORD)

Left edge of the drop zone, relative to the window width; a value of -10 would create a zone located 10 pixels left of the window right edge.

WBDZA_Top (WORD)

Top edge of the drop zone; a value of 0 would create a zone located at the top corner of the window.

WBDZA_RelBottom (WORD)

Top edge of the drop zone, relative to the window height; a value of -10 would create a zone located 10 pixels above the window bottom edge.

WBDZA_Width (WORD)

Width of the drop zone.

WBDZA_RelWidth (WORD)

Width of the drop zone, relative to the width of the window; a value of -20 would create a zone that is by 20 pixels narrower than the window.

WBDZA_Height (WORD)

Height of the drop zone.

WBDZA_RelHeight (WORD)

Height of the drop zone, relative to the height of the window; a value of -20 would create a zone that is by 20 pixels smaller than the window.

WBDZA_Box (struct IBox *)

Position and size of the drop zone.

WBDZA_Hook (struct Hook *)

Pointer to 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);

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

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

see next

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!

dropZone

A newly created drop zone identifier, or NULL if it could not be created; use dos.library/IoErr to find out what caused it to fail.

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.

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 zones must be created with a position and a size. If you omit either one, this routine will fail.

When an icon is dropped on a drop zone, the AppMessage am_MouseX and am_MouseY members will be relative to the window top left corner; they WILL NOT be relative to the left/top edge of the drop zone.

dos.library/IoErr(), AddAppWindowA()