Package | flash.desktop |
Class | public class NativeDragManager |
Inheritance | NativeDragManager Object |
Runtime Versions: | AIR 1.0 |
The following kinds of data can be transferred:
- Bitmaps
- Files
- Text
- 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.
Drag actions
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 allowedActions
parameter
in the NativeDragManager.doDrag()
call that starts the drag operation.
If no 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
the nativeDragEnter
and 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
acceptDrop()
method.
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 NativeDragManager.doDrag()
method
within a mouseDown
or mouseMove
event handler and
proceeds through the following event sequence in response to user actions:
-
nativeDragStart
event — WhenNativeDragManager.doDrag()
is called, the interactive object passed as a paramter to the method becomes the initiator object and dispatches anativeDragStart
event. -
nativeDragUpdate
event — While the drag is in progress, the initiator object continually dispatchesnativeDragUpdate
events. -
nativeDragEnter
,nativeDragOver
events — When a drag gesture passes over an interactive object, that object dispatches anativeDragEnter
event. While the drag gesture remains over the interactive object, it continually dispatchesnativeDragOver
events. 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 callNativeDragManager.acceptDrop()
, passing in a reference to the display object to serve as the drag target (typically the object that dispatched thenativeDragEnter
ornativeDragOver
event). The user can then drop the dragged item onto the target. -
nativeDragExit
event — When a drag gesture passes out of an interactive object, the object dispatches anativeDragExit
event. If the object had been designated as the drag target by an earlier call to theNativeDragManager.acceptDrop()
method, that call is no longer valid andacceptDrop()
must be called again if the gesture re-enters the interactive object. -
nativeDragDrop
event — The target display object dispatches anativeDragDrop
event when the user releases the mouse button over the object. The handler for this event can access the data in thetransferable
property of the event object and should set theNativeDragManager.dropAction
property 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 anativeDragComplete
event (whether or not the drop itself was consumated). The handler for this event can check thedropAction
property 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. IfdropAction
isNativeDragActions.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 nativeDragStart
or nativeDragComplete
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
nativeDragEnter
, nativeDragOver
, or 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.
Transfering information
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.
Security considerations
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 clipboard
property to determine which data formats are available, but calling the
clipboard.getData()
method generates a security error.
See also
flash.desktop.NativeDragActions
flash.desktop.NativeDragOptions
flash.desktop.Clipboard
Property | Defined By | ||
---|---|---|---|
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
dragInitiator : InteractiveObject [static] [read-only]
The interactive object passed to the NativeDragManager.doDrag() call that initiated the drag operation. | NativeDragManager | ||
dropAction : String [static]
The drag action specified by the drop target. | NativeDragManager | ||
isDragging : Boolean [static] [read-only]
Reports whether a drag operation is currently in progress. | NativeDragManager | ||
prototype : Object [static]
A reference to the prototype object of a class or function object. | Object |
Method | Defined By | ||
---|---|---|---|
[static]
Informs the NativeDragManager object that the specified target interactive object can accept a drop
corresponding to the current drag event. | NativeDragManager | ||
doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void [static]
Starts a drag-and-drop operation. | NativeDragManager | ||
Indicates whether an object has a specified property defined. | Object | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
Returns the string representation of the specified object. | Object | ||
Returns the primitive value of the specified object. | Object |
dragInitiator | property |
dragInitiator:InteractiveObject
[read-only] Runtime Versions: | AIR 1.0 |
The interactive object passed to the NativeDragManager.doDrag()
call that initiated the drag operation.
Implementation
public static function get dragInitiator():InteractiveObject
dropAction | property |
dropAction:String
Runtime Versions: | AIR 1.0 |
The drag action specified by the drop target.
The dropAction
property
should be set in the handler for the nativeDragDrop
event.
If dropAction
is not set before the nativeDragComplete
,
the NativeDragManager sets the value with the first
allowed action from the list: copy, move, or link (in that order).
Implementation
public static function get dropAction():String
public static function set dropAction(value:String):void
See also
isDragging | property |
isDragging:Boolean
[read-only] Runtime Versions: | AIR 1.0 |
Reports whether a drag operation is currently in progress.
Implementation
public static function get isDragging():Boolean
acceptDragDrop | () | method |
public static function acceptDragDrop(target:InteractiveObject):void
Runtime Versions: | AIR 1.0 |
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 nativeDragDrop
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 nativeDragEnter
or nativeDragOver
event handler.
Parameters
target:InteractiveObject |
doDrag | () | method |
public static function doDrag(dragInitiator:InteractiveObject, clipboard:Clipboard, dragImage:BitmapData = null, offset:Point = null, allowedActions:NativeDragOptions = null):void
Runtime Versions: | AIR 1.0 |
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.
(If the
allowedActions
parameter is leftnull
, all actions are allowed.) - Call
NativeDragManager.doDrag()
.
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.
If dropAction
is NativeDragActions.NONE
, then the dragged item was not dropped
on an eligible target.
This method can be called only from within a mouseDown
or
mouseMove
event handler. (If called in response to a
mouseMove
event, the mouse button must also be down.)
Parameters
dragInitiator:InteractiveObject — Typically the object from which the drag gesture began. Receives the nativeDragStart
and nativeDragComplete events.
| |
clipboard:Clipboard — The container object for data being dragged.
| |
dragImage:BitmapData (default = null ) — An optional proxy image displayed under the mouse pointer
during the drag gesture. If null , no image is displayed.
| |
offset:Point (default = null ) — 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 = null ) — Restricts the drag-and-drop actions allowed for
this operation. If null , all actions are allowed.
|
See also
Fri Mar 19 2010, 02:45 AM -07:00