widget/nsIDragSession.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 "nsISupports.idl"
   8 #include "nsITransferable.idl"
   9
  10
  11
  12 %{ C++
  13 #include "mozilla/EventForwards.h"
  14 #include "nsIWidget.h"
  15 #include "nsSize.h"
  16 #include "Units.h"
  17
  18 class nsIFrame;
  19 class nsIWidget;
  20
  21 namespace mozilla {
  22 namespace dom {
  23 class BrowserParent;
  24 } // namespace dom
  25 } // namespace mozilla
  26 %}
  27
  28 interface nsIContentSecurityPolicy;
  29
  30 [ptr] native BrowserParentPtr(mozilla::dom::BrowserParent);
  31 native EventMessage(mozilla::EventMessage);
  32 [ref] native LayoutDeviceIntPoint(mozilla::LayoutDeviceIntPoint);
  33 [ptr] native nsIFramePtr(nsIFrame);
  34 [ptr] native nsIWidgetPtr(nsIWidget);
  35 native nsSize(nsSize);
  36
  37 webidl DataTransfer;
  38 webidl DragEvent;
  39 webidl Element;
  40 webidl WindowContext;
  41 webidl Node;
  42 webidl Selection;
  43
  44 [scriptable, builtinclass, uuid(25bce737-73f0-43c7-bc20-c71044a73c5a)]
  45 interface nsIDragSession : nsISupports
  46 {
  47   /**
  48     * Set the current state of the drag, whether it can be dropped or not.
  49     * usually the target "frame" sets this so the native system can render the correct feedback
  50     */
  51   attribute boolean canDrop;
  52
  53   /**
  54    * Indicates if the drop event should be dispatched only to chrome.
  55    */
  56   attribute boolean onlyChromeDrop;
  57
  58   /**
  59     * Sets the action (copy, move, link, et.c) for the current drag
  60     */
  61   attribute unsigned long dragAction;
  62
  63   /**
  64     * Get the number of items that were dropped
  65     */
  66   readonly attribute unsigned long numDropItems;
  67
  68   /**
  69     * The window context where the drag was started, which will be null if the
  70     * drag originated outside the application. Useful for determining if a drop
  71     * originated in the same window context.
  72     */
  73   [infallible]
  74   attribute WindowContext sourceWindowContext;
  75
  76   /**
  77     * The top-level window context where the drag was started, which will be
  78     * null if the drag originated outside the application. Useful for
  79     * determining if a drop originated in the same top-level window context.
  80     */
  81   [infallible]
  82   attribute WindowContext sourceTopWindowContext;
  83
  84   /**
  85     * The dom node that was originally dragged to start the session, which will be null if the
  86     * drag originated outside the application.
  87     */
  88   readonly attribute Node sourceNode;
  89
  90   /**
  91    * Replace source node and selection with new ones.
  92    * If sourceNode is a native anonymous node, it may be replaced at reframing.
  93    * If sourceNode is disconnected from the document, we cannot dispatch
  94    * `dragend` event properly.
  95    * When this is called, sourceNode or aNewSourceNode should be a native
  96    * anonymous node.
  97    */
  98   [notxpcom, nostdcall] void updateSource(in Node aNewSourceNode,
  99                                           in Selection aNewSelection);
 100
 101   /**
 102    * the triggering principal.  This may be different than sourceNode's
 103    * principal when sourceNode is xul:browser and the drag is
 104    * triggered in a browsing context inside it.
 105    */
 106   attribute nsIPrincipal triggeringPrincipal;
 107
 108   /**
 109    * the triggering csp.  This may be different than sourceNode's
 110    * csp when sourceNode is xul:browser and the drag is
 111    * triggered in a browsing context inside it.
 112    */
 113   attribute nsIContentSecurityPolicy csp;
 114
 115   /**
 116    * The data transfer object for the current drag.
 117    */
 118   [binaryname(DataTransferXPCOM)]
 119   attribute DataTransfer dataTransfer;
 120   [notxpcom, nostdcall] DataTransfer getDataTransfer();
 121   [notxpcom, nostdcall] void setDataTransfer(in DataTransfer aDataTransfer);
 122
 123   /**
 124     * Get data from a Drag&Drop. Can be called while the drag is in process
 125     * or after the drop has completed.
 126     *
 127     * @param  aTransferable the transferable for the data to be put into
 128     * @param  aItemIndex which of multiple drag items, zero-based
 129     */
 130   void getData ( in nsITransferable aTransferable, in unsigned long aItemIndex ) ;
 131
 132    /**
 133     * Check to set if any of the native data on the clipboard matches this data flavor
 134     */
 135   boolean isDataFlavorSupported ( in string aDataFlavor ) ;
 136
 137   void userCancelled();
 138
 139   void dragEventDispatchedToChildProcess();
 140
 141   // Called when nsIDragSession implementation should update the UI for the
 142   // drag-and-drop based on the data got from the child process in response to
 143   // NS_DRAGDROP_OVER sent from parent process to child process.
 144   void updateDragEffect();
 145
 146   // Change the drag image, using similar arguments as
 147   // nsIDragService::InvokeDragSessionWithImage.
 148   void updateDragImage(in Node aImage, in long aImageX, in long aImageY);
 149
 150   /**
 151    * Tell Gecko that this session is generated for automated testing.
 152    * This should be called immediately after StartDragSession when testing.
 153    */
 154   [noscript] void InitForTests(in uint32_t aAllowedEffect);
 155
 156   /**
 157    * Returns effects allowed at starting the session for tests.
 158    */
 159   [notxpcom, nostdcall] unsigned long getEffectAllowedForTests();
 160
 161   /**
 162    * Returns true if current session was started with synthesized drag start.
 163    */
 164   [notxpcom, nostdcall] boolean isSynthesizedForTests();
 165
 166   /**
 167    * Sets the drag end point.  Position is relative to screen in device coords.
 168    */
 169   void setDragEndPoint(in long aScreenX, in long aScreenY);
 170
 171   /**
 172    * Sets drag end point of synthesized session when the test does not dispatch
 173    * "drop" event.
 174    */
 175   void setDragEndPointForTests(in long aScreenX, in long aScreenY);
 176
 177   /**
 178    * Returns true if the session is for dragging text in a text in text control
 179    * element.
 180    */
 181   [notxpcom, nostdcall] boolean isDraggingTextInTextControl();
 182
 183   /**
 184    * Called when HTMLEditor maybe deleted the source node from the document.
 185    *
 186    * @param aEditingHost    The editing host when the editor deletes selection.
 187    */
 188   [noscript] void maybeEditorDeletedSourceNode(in Element aEditingHost);
 189
 190   /**
 191     * aX and aY are in LayoutDevice pixels.
 192     */
 193   [noscript] void dragMoved(in long aX, in long aY);
 194
 195   /**
 196    * Fire a drag event at the source of the drag
 197    */
 198   [noscript, can_run_script]
 199   void fireDragEventAtSource(in EventMessage aEventMessage,
 200                              in unsigned long aKeyModifiers);
 201
 202   [notxpcom, nostdcall] boolean maybeAddBrowser(in BrowserParentPtr aBP);
 203   [notxpcom, nostdcall] boolean removeAllBrowsers();
 204
 205   /**
 206     * Tells the Drag Service to end a drag session.
 207     *
 208     * If aDoneDrag is true, the drag has finished, otherwise the drag has
 209     * just left the window.
 210     *
 211     * @param aDoneDrag       If true, reports the drag as complete.
 212     * @param aKeyModifiers   Key state to assume while ending the session.
 213     */
 214   [can_run_script]
 215   void endDragSession(in boolean aDoneDrag,
 216                       [optional] in unsigned long aKeyModifiers);
 217
 218   /**
 219    * Tell the drag session for the given browser that it
 220    * should store the would-be target of the aEvent (a drop event) and delay
 221    * calls to EndDragSession.  This is used in the main process.
 222    *
 223    * @param aEvent The drag event
 224    */
 225   void sendStoreDropTargetAndDelayEndDragSession(
 226       in DragEvent aEvent);
 227
 228   /**
 229    * After sendStoreDropTargetAndDelayEndDragSession, send a drop (if
 230    * aShouldDrop is true) or dragexit event to the recorded drop target and
 231    * then reissue any stored EndDragSession call.  This is used in the main
 232    * process.
 233    *
 234    * @param aShouldDrop  True to send drop event, false to send dragexit event
 235    */
 236   void sendDispatchToDropTargetAndResumeEndDragSession(
 237       in boolean aShouldDrop);
 238
 239   /**
 240    * Store aElement and aDocFrame as the future drop/dragexit context, and
 241    * delay calls to EndDragSession.  This is used in content processes.
 242    *
 243    * @param aElement        The element to drop onto
 244    * @param aDocFrame       The frame to dispatch to
 245    */
 246   [noscript] void storeDropTargetAndDelayEndDragSession(
 247       in Element aElement,
 248       in nsIFramePtr aDocFrame
 249   );
 250
 251   /**
 252    * Issue drop or dragexit to the stored drop target (if any) and issue
 253    * any delayed call to EndDragSession.  This is used in content processes.
 254    *
 255    * @param aWidget      The widget on which the drop will happen
 256    * @param aPt          Screen coords of drop
 257    * @param aShouldDrop  If true, send a drop event.  Otherwise send dragexit.
 258    */
 259   [noscript, can_run_script]
 260   void dispatchToDropTargetAndResumeEndDragSession(
 261       in nsIWidgetPtr aWidget,
 262       [const] in LayoutDeviceIntPoint aPt,
 263       in boolean aShouldDrop);
 264
 265   /**
 266    * Retrun true if nsIDragSession's data is updated.
 267    */
 268   [notxpcom, nostdcall] boolean mustUpdateDataTransfer(in EventMessage aMessage);
 269 };