widget/public/nsIDragService.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corp.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Mike Pinkerton
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41 #include "nsISupportsArray.idl"
  42 #include "nsIDragSession.idl"
  43 #include "nsIScriptableRegion.idl"
  44
  45
  46 interface nsIDOMNode;
  47 interface nsIDOMDragEvent;
  48 interface nsIDOMDataTransfer;
  49 interface nsISelection;
  50
  51 [scriptable, uuid(82B58ADA-F490-4C3D-B737-1057C4F1D052)]
  52 interface nsIDragService : nsISupports
  53 {
  54   const long DRAGDROP_ACTION_NONE = 0;
  55   const long DRAGDROP_ACTION_COPY = 1;
  56   const long DRAGDROP_ACTION_MOVE = 2;
  57   const long DRAGDROP_ACTION_LINK = 4;
  58   const long DRAGDROP_ACTION_UNINITIALIZED = 64;
  59
  60   /**
  61     * Starts a modal drag session with an array of transaferables
  62     *
  63     * @param  aTransferables - an array of transferables to be dragged
  64     * @param  aRegion - a region containing rectangles for cursor feedback,
  65     *            in window coordinates.
  66     * @param  aActionType - specified which of copy/move/link are allowed
  67     */
  68   void invokeDragSession ( in nsIDOMNode aDOMNode, in nsISupportsArray aTransferables,
  69                              in nsIScriptableRegion aRegion, in unsigned long aActionType );
  70
  71   /**
  72    * Starts a modal drag session using an image. The first four arguments are
  73    * the same as invokeDragSession.
  74    *
  75    * A custom image may be specified using the aImage argument. If this is
  76    * supplied, the aImageX and aImageY arguments specify the offset within
  77    * the image where the cursor would be positioned. That is, when the image
  78    * is drawn, it is offset up and left the amount so that the cursor appears
  79    * at that location within the image.
  80    *
  81    * If aImage is null, aImageX and aImageY are not used and the image is instead
  82    * determined from the source node aDOMNode, and the offset calculated so that
  83    * the initial location for the image appears in the same screen position as
  84    * where the element is located. The node must be within a document.
  85    *
  86    * Currently, supported images are all DOM nodes. If this is an HTML <image> or
  87    * <canvas>, the drag image is taken from the image data. If the element is in
  88    * a document, it will be rendered at its displayed size, othewise, it will be
  89    * rendered at its real size. For other types of elements, the element is
  90    * rendered into an offscreen buffer in the same manner as it is currently
  91    * displayed. The document selection is hidden while drawing.
  92    *
  93    * The aDragEvent must be supplied as the current screen coordinates of the
  94    * event are needed to calculate the image location.
  95    */
  96   void invokeDragSessionWithImage(in nsIDOMNode aDOMNode,
  97                                   in nsISupportsArray aTransferableArray,
  98                                   in nsIScriptableRegion aRegion,
  99                                   in unsigned long aActionType,
 100                                   in nsIDOMNode aImage,
 101                                   in long aImageX,
 102                                   in long aImageY,
 103                                   in nsIDOMDragEvent aDragEvent,
 104                                   in nsIDOMDataTransfer aDataTransfer);
 105
 106   /**
 107    * Start a modal drag session using the selection as the drag image.
 108    * The aDragEvent must be supplied as the current screen coordinates of the
 109    * event are needed to calculate the image location.
 110    */
 111   void invokeDragSessionWithSelection(in nsISelection aSelection,
 112                                       in nsISupportsArray aTransferableArray,
 113                                       in unsigned long aActionType,
 114                                       in nsIDOMDragEvent aDragEvent,
 115                                       in nsIDOMDataTransfer aDataTransfer);
 116
 117   /**
 118     * Returns the current Drag Session
 119     */
 120   nsIDragSession getCurrentSession ( ) ;
 121
 122   /**
 123     * Tells the Drag Service to start a drag session. This is called when
 124     * an external drag occurs
 125     */
 126   void startDragSession ( ) ;
 127
 128   /**
 129     * Tells the Drag Service to end a drag session. This is called when
 130     * an external drag occurs
 131     *
 132     * If aDoneDrag is true, the drag has finished, otherwise the drag has
 133     * just left the window.
 134     */
 135   void endDragSession ( in PRBool aDoneDrag ) ;
 136
 137   /**
 138    * Fire a drag event at the source of the drag
 139    */
 140   void fireDragEventAtSource ( in unsigned long aMsg );
 141
 142   /**
 143    * Increase/decrease dragging suppress level by one.
 144    * If level is greater than one, dragging is disabled.
 145    */
 146   void suppress();
 147   void unsuppress();
 148 };
 149
 150
 151 %{ C++
 152
 153 %}