nsIDragService

Table of contents

  1. 1. Method overview
  2. 2. Constants
  3. 3. Methods
    1. 3.1. dragMoved()
    2. 3.2. endDragSession()
    3. 3.3. fireDragEventAtSource()
    4. 3.4. getCurrentSession()
    5. 3.5. invokeDragSession()
    6. 3.6. invokeDragSessionWithImage()
    7. 3.7. invokeDragSessionWithSelection()
    8. 3.8. startDragSession()
    9. 3.9. suppress()
    10. 3.10. unsuppress()
Page Notifications Off

Implements the Drag Service for handling drag and drop operations.
Inherits from: nsISupports Last changed in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

Note: Using this interface directly from add-on code is deprecated. Add-ons should use the standard dataTransfer drag and drop API instead. The only exception is getCurrentSession(), since there's currently no way to check for a drag in progress using standard DOM methods or properties.

Method overview

void endDragSession( in PRBool aDoneDrag ) ;
void dragMoved(in long aX, in long aY); Requires Gecko 9.0 Native code only!
void fireDragEventAtSource( in unsigned long aMsg ); Requires Gecko 1.9
nsIDragSession getCurrentSession( ) ;
void invokeDragSession( in nsIDOMNode aDOMNode, in nsISupportsArray aTransferables, in nsIScriptableRegion aRegion, in unsigned long aActionType );
void invokeDragSessionWithImage(in nsIDOMNode aDOMNode, in nsISupportsArray aTransferableArray, in nsIScriptableRegion aRegion, in unsigned long aActionType, in nsIDOMNode aImage, in long aImageX, in long aImageY, in nsIDOMDragEvent aDragEvent, in nsIDOMDataTransfer aDataTransfer); Requires Gecko 1.9
void invokeDragSessionWithSelection(in nsISelection aSelection, in nsISupportsArray aTransferableArray, in unsigned long aActionType, in nsIDOMDragEvent aDragEvent, in nsIDOMDataTransfer aDataTransfer); Requires Gecko 1.9
void startDragSession( ) ;
void suppress(); Requires Gecko 1.9
void unsuppress(); Requires Gecko 1.9

Constants

Constant Value Description
DRAGDROP_ACTION_NONE 0 No action.
DRAGDROP_ACTION_COPY 1 The drag and drop operation should copy the object.
DRAGDROP_ACTION_MOVE 2 The drag and drop operation should move the object.
DRAGDROP_ACTION_LINK 4 The drag and drop operation should link the object.
DRAGDROP_ACTION_UNINITIALIZED 64 The action is not initialized. Requires Gecko 1.9.1

Methods

Native code only!

dragMoved()

Introduced in Gecko 9.0

(Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

Programmatically changes the drag position of the drag session. This is used on Mac and Windows to update the position of a popup being used as a drag image during the drag operation. It's not used on GTK, which handles the drag popup itself.

[noscript] void dragMoved(
  in long aX,
  in long aY
);
Parameters
aX
The X coordinate to which to move the popup being dragged.
aY
The Y coordinate to which to move the popup being dragged.

endDragSession()

Tells the Drag Service to end a drag session. This is called when an external drag occurs.

void endDragSession(
  in PRBool aDoneDrag  
Requires Gecko 1.9

);
Parameters
aDoneDrag Requires Gecko 1.9
If aDoneDrag is true, the drag has finished, otherwise the drag has just left the window.

Requires Gecko 1.9 (Firefox 3)

fireDragEventAtSource()

Fire a drag event at the source of the drag.

void fireDragEventAtSource(
  in unsigned long aMsg 
);
Parameters
aMsg
One of the NS_DRAGDROP_* contants defined in widget/public/nsGUIEvent.h

getCurrentSession()

Returns the current Drag Session.

nsIDragSession getCurrentSession();
Parameters

None.

Return value

The current drag session, or null if no drag is in progress.

invokeDragSession()

Starts a modal drag session with an array of transferables

void invokeDragSession(
  in nsIDOMNode aDOMNode,
  in nsISupportsArray aTransferables,
  in nsIScriptableRegion aRegion,
  in unsigned long aActionType 
);
Parameters
aDOMNode
The source node on which the drag gesture was started.
aTransferables
An array of transferables to be dragged.
aRegion
A region containing rectangles for cursor feedback, in window coordinates.
aActionType
Specified which of copy/move/link are allowed.

Requires Gecko 1.9 (Firefox 3)

invokeDragSessionWithImage()

Starts a modal drag session using an image.

A custom image may be specified using the aImage argument. If this is supplied, the aImageX and aImageY arguments specify the offset within the image where the cursor would be positioned. That is, when the image is drawn, it is offset up and left the amount so that the cursor appears at that location within the image. If aImage is null, aImageX and aImageY are not used and the image is instead determined from the source node aDOMNode, and the offset calculated so that the initial location for the image appears in the same screen position as where the element is located. The node must be within a document.

Currently, supported images are all DOM nodes. If this is an HTML <image> or <canvas> element, the drag image is taken from the image data. If the element is in a document, it will be rendered at its displayed size, otherwise, it will be rendered at its real size. For other types of elements, the element is rendered into an offscreen buffer in the same manner as it is currently displayed. The document selection is hidden while drawing. The aDragEvent must be supplied as the current screen coordinates of the event are needed to calculate the image location.

void invokeDragSessionWithImage(
  in nsIDOMNode aDOMNode,
  in nsISupportsArray aTransferableArray,
  in nsIScriptableRegion aRegion,
  in unsigned long aActionType,
  in nsIDOMNode aImage,
  in long aImageX,
  in long aImageY,
  in nsIDOMDragEvent aDragEvent,
  in nsIDOMDataTransfer aDataTransfer 
Requires Gecko 1.9.1

);
Parameters
aDOMNode
The source node on which the drag gesture was started.
aTransferables
An array of transferables to be dragged.
aRegion
A region containing rectangles for cursor feedback, in window coordinates.
aActionType
Specified which of copy/move/link are allowed.
aImage
Image object.
aImageX
X position of image.
aImageY
Y position of image.
aDragEvent
The drag gesture event that initiated the drag.
aDataTransfer Requires Gecko 1.9.1
A data transfer object that is available on the current drag session.

Requires Gecko 1.9 (Firefox 3)

invokeDragSessionWithSelection()

Start a modal drag session using the selection as the drag image. The aDragEvent must be supplied as the current screen coordinates of the event are needed to calculate the image location.

void invokeDragSessionWithSelection(
  in nsISelection aSelection,
  in nsISupportsArray aTransferableArray,
  in unsigned long aActionType,
  in nsIDOMDragEvent aDragEvent,
  in nsIDOMDataTransfer aDataTransfer 
Requires Gecko 1.9.1

);
Parameters
aSelection
The selection that is to be dragged.
aTransferableArray
An array of transferables to be dragged.
aActionType
Specified which of copy/move/link are allowed
aDragEvent
The drag gesture event that initiated the drag.
aDataTransfer Requires Gecko 1.9.1
A data transfer object that is available on the current drag session.

startDragSession()

Tells the Drag Service to start a drag session. This is called when an external drag occurs

void startDragSession();
Parameters

None.

Requires Gecko 1.9 (Firefox 3)

suppress()

Increase dragging suppress level by one. This disables dragging if it is not already disabled.

void suppress();
Parameters

None.

Requires Gecko 1.9 (Firefox 3)

unsuppress()

Decrease dragging suppress level by one. If level is zero, dragging is re-enabled.

void unsuppress();
Parameters

None.

Tags (5)

Edit tags

Attachments (0)

 

Attach file