|public class NativeDragManager
The following kinds of data can be transferred:
- URL strings
- Serialized objects
- Object references (valid only within the originating application)
Note: all NativeDragManager members are static. An instance of this class does not need to be created.
A drag-and-drop operation is a user interface gesture that begins with the user clicking a visible item and dragging it elsewhere. During the drag gesture, interactive objects on the display list dispatch native drag events as the gesture moves across the AIR application window. Handlers for these events can call the methods of the NativeDragManager class to indicate whether a dragged item can be dropped on an object. In response, the NativeDragManager changes the mouse pointer to provide feedback to the user.
AIR profile support: This feature is not supported
on AIR for TV devices. Also, it is not supported on all mobile devices. You can test
for support at run time using the
NativeDragManager.isSupported property. See
AIR Profile Support for more information regarding API support across multiple profiles.
Drag-and-drop gestures are typically used for three types of operations, called actions. Since the meaning of these actions depends on the application context, the runtime does not enforce any particular behavior with respect to actions. However, properly implementing the actions improves the user experience with your application.
The possible actions are:
- Copy — A copy of the data is made, leaving the original untouched. (When dragging objects within an application, care should be taken to copy the original object itself rather than the reference to that object.)
- Move — The data is moved from its original context into the context defined by the drop target, such as when moving an item from one list to another.
- Link — A reference or shortcut to the original data is created, leaving the item in its original context.
The allowed actions can be set for a drag gesture by supplying an
NativeDragManager.doDrag() call that starts the drag operation.
allowedActions parameter is provided, all
of the actions are allowed. Potential drag targets can check which actions are allowed by using the
allowedActions property of a NativeDragEvent object, and should not accept a drop
that allows only incompatible actions (this is not enforced by the runtime, however).
If a drop target only implements a single action, the object can set the
dropAction property of the NativeDragManager in the handlers for both
nativeDragOver events. Setting the
property before the drop, allows the drag manager to update the mouse pointer to
indicate the supported action and also prevents
a user from choosing an incompatible action using modifier keys. If the specified action
is not one of the allowed actions, then a drop is not allowed, even if the target calls the
When accepting a drop, a potential drop target should specify the action chosen
by setting the
NativeDragManager.dropAction property in response to the
nativeDragDrop event. This action is reported back to the initiating
display object in the
nativeDragComplete event. If no action is set by a drop target,
then a default action is chosen from the allowed actions in this order of
precedence: copy, move, link. The initiating object is responsible
for updating its internal state in response to the chosen action.
String constants for the action names are defined in the NativeDragActions class.
Sequence of events
A drag gesture is begun by calling the
mouseMove event handler and
proceeds through the following event sequence in response to user actions:
nativeDragStartevent — When
NativeDragManager.doDrag()is called, the interactive object passed as a paramter to the method becomes the initiator object and dispatches a
nativeDragUpdateevent — While the drag is in progress, the initiator object continually dispatches
nativeDragOverevents — When a drag gesture passes over an interactive object, that object dispatches a
nativeDragEnterevent. While the drag gesture remains over the interactive object, it continually dispatches
nativeDragOverevents. In response to either of these events, an object that serves as a potential drop target should check the properties of the event object to decide whether it can accept the drop. If the data format and allowed actions are appropriate, then the event handler for these events must call
NativeDragManager.acceptDrop(), passing in a reference to the display object to serve as the drag target (typically the object that dispatched the
nativeDragOverevent). The user can then drop the dragged item onto the target.
nativeDragExitevent — When a drag gesture passes out of an interactive object, the object dispatches a
nativeDragExitevent. If the object had been designated as the drag target by an earlier call to the
NativeDragManager.acceptDrop()method, that call is no longer valid and
acceptDrop()must be called again if the gesture re-enters the interactive object.
nativeDragDropevent — The target display object dispatches a
nativeDragDropevent when the user releases the mouse button over the object. The handler for this event can access the data in the
transferableproperty of the event object and should set the
NativeDragManager.dropActionproperty to signal which action should be taken by the initiator object.
nativeDragComplete— When the user releases the mouse button at the end of a drag gesture, the initiator object dispatches a
nativeDragCompleteevent (whether or not the drop itself was consumated). The handler for this event can check the
dropActionproperty of the event object to determine what, if any, modification should be made to its internal data state, such as removing a dragged-out item from a list. If
NativeDragActions.NONE, then the dragged item was not dropped on an eligible target.
Gestures between applications
When a drag gesture enters an AIR application window from a non-AIR application,
there is no initiator object to dispatch the
event. The events dispatched during the gesture will otherwise follow the same
pattern as that of a gesture starting and ending within the same AIR application.
When a drag gesture leaves an AIR application window, there is no target object to dispatch
nativeDragDrop events. The initiator object
still dispatches a
nativeDragComplete event, which reports the drag action set
by the native operating system (or
none, if the drop was not accepted).
When a drag gesture moves from one AIR application to another, the initiator and target display objects dispatch events within their separate applications as usual.
The data transfered during a drag-and-drop gesture is contained in a Clipboard object.
This data object is added to the drag operation with the
NativeDragManager.doDrag() method that starts the drag gesture.
Potential drop targets can access the Clipboard object through the
clipboard property of the native drag event
object. Once a drag operation has started, the Clipboard object can
only be accessed in the event handler of a NativeDragEvent. Any other attempt
to access the object generates a run-time error.
The security sandboxes of the initiator and potential target objects determine how the
the data being dragged can be accessed. If both objects are in the same sandbox,
then the data can be accessed from any NativeDragEvent object. However,
if the initiator and target objects are in different sandboxes, the data can
only be accessed in the target sandbox within the event
handler for the
nativeDragDrop event. Other native drag event handlers can still
still access the Clipboard object referenced in the event
property to determine which data formats are available, but calling the
clipboard.getData() method generates a security error.
Related API Elements
|constructor : Object
A reference to the class object or constructor function for a given object instance.
| dragInitiator : InteractiveObject
[static] [read-only] The interactive object passed to the NativeDragManager.doDrag() call that initiated the drag operation.
| dropAction : String
[static] The drag action specified by the drop target.
| isDragging : Boolean
[static] [read-only] Reports whether a drag operation is currently in progress.
| isSupported : Boolean
[static] [read-only] The isSupported property is set to true if the NativeDragManager class is supported on the current platform, otherwise it is set to false.
[static] Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event.
doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void
[static] Starts a drag-and-drop operation.
Indicates whether an object has a specified property defined.
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Indicates whether the specified property exists and is enumerable.
Sets the availability of a dynamic property for loop operations.
Returns the string representation of this object, formatted according to locale-specific conventions.
Returns the string representation of the specified object.
Returns the primitive value of the specified object.
The drag action specified by the drop target.
should be set in the handler for the
dropAction is not set before the
the NativeDragManager sets the value with the first
allowed action from the list: copy, move, or link (in that order).
public static function get dropAction():String
public static function set dropAction(value:String):void
Related API Elements
public static function acceptDragDrop(target:InteractiveObject):void
Informs the NativeDragManager object that the specified target interactive object can accept a drop corresponding to the current drag event.
This method should be called only when there is a
handler on the specified target object that can handle at least one of the
data formats in the dragged item and at least one of the allowed actions.
This function can be called only within a
public static function doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void
Starts a drag-and-drop operation.
To start a drag operation:
- Create a new Clipboard object.
- Add the data to be transferred in one or more formats.
- Optionally, create a BitmapData object to serve as a proxy image during the drag.
- Optionally, create a NativeDragOptions object to restrict the actions allowed in this operation.
allowedActionsparameter is left
null, all actions are allowed.)
The initiator object dispatches a
nativeDragStart event after this method is called,
nativeDragStart events while the drag is in progress, and a
nativeDragComplete event when the user releases the mouse button to end the drag gesture.
The handler for the
nativeDragComplete event can check the
dropAction property of the
event to determine whether the drag-and-drop operation was successfully completed.
NativeDragActions.NONE, then the dragged item was not dropped
on an eligible target.
This method can be called only from within a
mouseMove event handler. (If called in response to a
mouseMove event, the mouse button must also be down.)
dragInitiator:InteractiveObject — Typically the object from which the drag gesture began. Receives the
clipboard:Clipboard — The container object for data being dragged.
dragImage:BitmapData (default =
— An optional proxy image displayed under the mouse pointer
during the drag gesture. If
null, no image is displayed.
offset:Point (default =
— The offset between the mouse hotspot and the top left
corner of the drag image. Negative coordinates move the image up and
to the left in relation to the hotspot. If
null, the top
left corner of the drag image is positioned at the mouse hotspot.
allowedActions:NativeDragOptions (default =
— Restricts the drag-and-drop actions allowed for
this operation. If
null, all actions are allowed.
Related API Elements
Thu Dec 6 2018, 01:12 PM -08:00