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

   SYNOPSIS
	dropZone = AddAppWindowDropZoneA(appWindow,id,userData,tags)
	   D0                               A0    D0    D1     A1

	struct AppWindowDropZone * AddAppWindowDropZoneA(struct AppWindow *aw,
	                           ULONG id,ULONG userData,
	                           struct TagItem * tags);

	dropZone = AddAppWindowDropZone(appWindow,id,userData,zone,...)

	struct AppWindowDropZone * AddAppWindowDropZone(struct AppWindow *aw,
	                           ULONG id,ULONG userData,...);

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

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

   TAGS
	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
	        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!

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

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

   SEE ALSO
	dos.library/IoErr
	workbench.library/AddAppWindowA

[Back to Amiga Developer Docs]