widget/nsIDragService.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsIArray.idl"
   8 #include "nsISupports.idl"
   9 #include "nsIDragSession.idl"
  10 #include "nsIContentPolicy.idl"
  11
  12 webidl DragEvent;
  13 webidl Node;
  14 webidl Selection;
  15
  16 interface nsICookieJarSettings;
  17 interface nsIMockDragServiceController;
  18
  19 %{C++
  20 #include "mozilla/EventForwards.h"
  21 #include "nsIWidget.h"
  22
  23 class nsIWidget;
  24
  25 namespace mozilla {
  26 namespace dom {
  27 class BrowserParent;
  28 class DataTransfer;
  29 class RemoteDragStartData;
  30 } // namespace dom
  31 } // namespace mozilla
  32 %}
  33
  34 [ptr] native BrowserParentPtr(mozilla::dom::BrowserParent);
  35 [ptr] native DataTransferPtr(mozilla::dom::DataTransfer);
  36 [ptr] native RemoteDragStartDataPtr(mozilla::dom::RemoteDragStartData);
  37 native EventMessage(mozilla::EventMessage);
  38
  39 [scriptable, uuid(ebd6b3a2-af16-43af-a698-3091a087dd62), builtinclass]
  40 interface nsIDragService : nsISupports
  41 {
  42   const long DRAGDROP_ACTION_NONE = 0;
  43   const long DRAGDROP_ACTION_COPY = 1;
  44   const long DRAGDROP_ACTION_MOVE = 2;
  45   const long DRAGDROP_ACTION_LINK = 4;
  46   const long DRAGDROP_ACTION_UNINITIALIZED = 64;
  47
  48   /**
  49    * Starts a modal drag session using an image. The first four arguments are
  50    * the same as invokeDragSession.
  51    *
  52    * Note: This method is deprecated for non-native code.
  53    *
  54    * A custom image may be specified using the aImage argument. If this is
  55    * supplied, the aImageX and aImageY arguments specify the offset within
  56    * the image where the cursor would be positioned. That is, when the image
  57    * is drawn, it is offset up and left the amount so that the cursor appears
  58    * at that location within the image.
  59    *
  60    * If aImage is null, aImageX and aImageY are not used and the image is instead
  61    * determined from the source node aDOMNode, and the offset calculated so that
  62    * the initial location for the image appears in the same screen position as
  63    * where the element is located. The node must be within a document.
  64    *
  65    * Currently, supported images are all DOM nodes. If this is an HTML <image> or
  66    * <canvas>, the drag image is taken from the image data. If the element is in
  67    * a document, it will be rendered at its displayed size, othewise, it will be
  68    * rendered at its real size. For other types of elements, the element is
  69    * rendered into an offscreen buffer in the same manner as it is currently
  70    * displayed. The document selection is hidden while drawing.
  71    *
  72    * The aDragEvent must be supplied as the current screen coordinates of the
  73    * event are needed to calculate the image location.
  74    */
  75   [noscript, can_run_script]
  76   void invokeDragSessionWithImage(in Node aDOMNode,
  77                                   in nsIPrincipal aPrincipal,
  78                                   in nsIContentSecurityPolicy aCsp,
  79                                   in nsICookieJarSettings aCookieJarSettings,
  80                                   in nsIArray aTransferableArray,
  81                                   in unsigned long aActionType,
  82                                   in Node aImage,
  83                                   in long aImageX,
  84                                   in long aImageY,
  85                                   in DragEvent aDragEvent,
  86                                   in DataTransferPtr aDataTransfer);
  87
  88   /** Start a drag session with the data in aDragStartData from a child process.
  89    *  Other arguments are the same as invokeDragSessionWithImage.
  90    */
  91   [noscript, can_run_script]
  92   void invokeDragSessionWithRemoteImage(in Node aDOMNode,
  93                                         in nsIPrincipal aPrincipal,
  94                                         in nsIContentSecurityPolicy aCsp,
  95                                         in nsICookieJarSettings aCookieJarSettings,
  96                                         in nsIArray aTransferableArray,
  97                                         in unsigned long aActionType,
  98                                         in RemoteDragStartDataPtr aDragStartData,
  99                                         in DragEvent aDragEvent,
 100                                         in DataTransferPtr aDataTransfer);
 101
 102   /**
 103    * Start a modal drag session using the selection as the drag image.
 104    * The aDragEvent must be supplied as the current screen coordinates of the
 105    * event are needed to calculate the image location.
 106    *
 107    * Note: This method is deprecated for non-native code.
 108    */
 109   [noscript, can_run_script]
 110   void invokeDragSessionWithSelection(in Selection aSelection,
 111                                       in nsIPrincipal aPrincipal,
 112                                       in nsIContentSecurityPolicy aCsp,
 113                                       in nsICookieJarSettings aCookieJarSettings,
 114                                       in nsIArray aTransferableArray,
 115                                       in unsigned long aActionType,
 116                                       in DragEvent aDragEvent,
 117                                       in DataTransferPtr aDataTransfer,
 118                                       in Node aTargetContent);
 119
 120   /**
 121     * In the parent process, returns the current drag session.  In content,
 122     * returns the current drag session for the widget containing the given
 123     * window, or the entry global JS context if aWindow is not specified.
 124     *
 125     * @param aWidgetProvider Either the nsIWidget that is the source or current
 126     *                        target of the drag, or an nsIDOMWindowProxy for a
 127     *                        window that is on the widget.
 128     */
 129   nsIDragSession getCurrentSession([optional] in nsISupports aWidgetProvider);
 130
 131 %{ C++
 132   nsIDragSession* GetCurrentSession(nsIWidget* aWidget) {
 133         nsCOMPtr<nsIDragSession> session;
 134     GetCurrentSession(aWidget, getter_AddRefs(session));
 135     return session;
 136   }
 137 %}
 138
 139   /**
 140     * Tells the Drag Service to start a drag session. This is called when
 141     * an external drag occurs.
 142     *
 143     * @param aWidgetProvider Either the nsIWidget that will be the target of
 144     *                        the drag, or an nsIDOMWindowProxy for a
 145     *                        window that is on that widget.
 146     * @returns the new (or pre-existing) session
 147     */
 148   [notxpcom, nostdcall]
 149   nsIDragSession startDragSession(in nsISupports aWidgetProvider);
 150
 151   /**
 152    * Similar to startDragSession(), automated tests may want to start
 153    * session for emulating an external drag.  At that time, this should
 154    * be used instead of startDragSession().
 155    *
 156    * @param aWidgetProvider Either the nsIWidget that is the source or current
 157    *                        target of the drag, or an nsIDOMWindowProxy for a
 158    *                        window that is on the widget.
 159    *
 160    * @param aAllowedEffect Set default drag action which means allowed effects
 161    *                       in the session and every DnD events are initialized
 162    *                       with one of specified value.  So, the value can be
 163    *                       DRAGDROP_ACTION_NONE, or one or more values of
 164    *                       DRAGDROP_ACTION_(MOVE|COPY|LINK).
 165    */
 166   void startDragSessionForTests(in nsISupports aWidgetProvider,
 167                                 in unsigned long aAllowedEffect);
 168
 169   /**
 170    * Increase/decrease dragging suppress level by one.
 171    * If level is greater than one, dragging is disabled.
 172    */
 173   [can_run_script]
 174   void suppress();
 175   void unsuppress();
 176
 177   [notxpcom, nostdcall] boolean maybeAddBrowser(in BrowserParentPtr aBP);
 178   [notxpcom, nostdcall] boolean removeAllBrowsers();
 179
 180   /**
 181    * The controller is used to issue events that would normally come from
 182    * the system (when it is not mocked for testing).  This allows us to test
 183    * without engaging any native DND behavior.
 184    *
 185    * In order for the controller to be effective, the existing nsIDragService
 186    * needs to be replaced with the one in the controller.  See
 187    * nsIMockDragServiceController for details.
 188    */
 189   nsIMockDragServiceController getMockDragController();
 190
 191   /**
 192    * True if this is a mock nsIDragService, created with
 193    * createMockDragController().
 194    */
 195   readonly attribute boolean isMockService;
 196
 197 %{ C++
 198   bool IsMockService() {
 199     bool ret = false;
 200     MOZ_ALWAYS_SUCCEEDS(GetIsMockService(&ret));
 201     return ret;
 202   }
 203 %}
 204
 205   /**
 206    * If this is true, mSessionIsSynthesizedForTests should not become true.
 207    * This hack is used to bypass the "old" drag-drop test behavior, which needed
 208    * special behavior to pass.  The new framework requires the actual browser
 209    * behavior.  The test for whether we are using the new framework or not can
 210    * only be done in the main process with nsBaseDragService::IsMockService.
 211    * Unfortunately, mSessionIsSynthesizedForTests is inherited from
 212    * synthetic mouse events in content processes (when dragging content) so we
 213    * set this early in the relevant tests.  Once the old tests are replaced,
 214    * this can be removed along with mSessionIsSynthesizedForTests.
 215    */
 216   [infallible] attribute boolean neverAllowSessionIsSynthesizedForTests;
 217 };
 218
 219
 220 %{ C++
 221
 222 %}