dom/webidl/FrameLoader.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 interface LoadContext;
   8 interface TabParent;
   9 interface URI;
  10 interface nsIDocShell;
  11 interface nsIPrintSettings;
  12 interface nsIWebBrowserPersistDocumentReceiver;
  13 interface nsIWebProgressListener;
  14
  15 [ChromeOnly]
  16 interface FrameLoader {
  17   /**
  18    * Get the docshell from the frame loader.
  19    */
  20   [GetterThrows]
  21   readonly attribute nsIDocShell? docShell;
  22
  23   /**
  24    * Get this frame loader's TabParent, if it has a remote frame.  Otherwise,
  25    * returns null.
  26    */
  27   readonly attribute TabParent? tabParent;
  28
  29   /**
  30    * Get an nsILoadContext for the top-level docshell. For remote
  31    * frames, a shim is returned that contains private browsing and app
  32    * information.
  33    */
  34   readonly attribute LoadContext loadContext;
  35
  36   /**
  37    * Get the root BrowsingContext within the frame.
  38    * This may be null immediately after creating a remote frame.
  39    */
  40   readonly attribute BrowsingContext? browsingContext;
  41
  42   /**
  43    * Get the ParentSHistory for the nsFrameLoader. May return null if this
  44    * frameloader is not for a toplevel frame.
  45    */
  46   readonly attribute ParentSHistory? parentSHistory;
  47
  48   /**
  49    * Find out whether the loader's frame is at too great a depth in
  50    * the frame tree.  This can be used to decide what operations may
  51    * or may not be allowed on the loader's docshell.
  52    */
  53   [Pure]
  54   readonly attribute boolean depthTooGreat;
  55
  56   /**
  57    * Activate remote frame.
  58    * Throws an exception with non-remote frames.
  59    */
  60   [Throws]
  61   void activateRemoteFrame();
  62
  63   /**
  64    * Deactivate remote frame.
  65    * Throws an exception with non-remote frames.
  66    */
  67   [Throws]
  68   void deactivateRemoteFrame();
  69
  70   /**
  71    * @see nsIDOMWindowUtils sendMouseEvent.
  72    */
  73   [Throws]
  74   void sendCrossProcessMouseEvent(DOMString aType,
  75                                   float aX,
  76                                   float aY,
  77                                   long aButton,
  78                                   long aClickCount,
  79                                   long aModifiers,
  80                                   optional boolean aIgnoreRootScrollFrame = false);
  81
  82   /**
  83    * Activate event forwarding from client (remote frame) to parent.
  84    */
  85   [Throws]
  86   void activateFrameEvent(DOMString aType, boolean capture);
  87
  88   // Note, when frameloaders are swapped, also messageManagers are swapped.
  89   readonly attribute MessageSender? messageManager;
  90
  91   /**
  92    * Request that the next time a remote layer transaction has been
  93    * received by the Compositor, a MozAfterRemoteFrame event be sent
  94    * to the window.
  95    */
  96   void requestNotifyAfterRemotePaint();
  97
  98   /**
  99    * Force a remote browser to recompute its dimension and screen position.
 100    */
 101   [Throws]
 102   void requestUpdatePosition();
 103
 104   /**
 105    * Print the current document.
 106    *
 107    * @param aOuterWindowID the ID of the outer window to print
 108    * @param aPrintSettings optional print settings to use; printSilent can be
 109    *                       set to prevent prompting.
 110    * @param aProgressListener optional print progress listener.
 111    */
 112   [Throws]
 113   void print(unsigned long long aOuterWindowID,
 114              nsIPrintSettings aPrintSettings,
 115              optional nsIWebProgressListener? aProgressListener = null);
 116
 117   /**
 118    * Renders a region of the frame into an image bitmap.
 119    *
 120    * @param x
 121    * @param y
 122    * @param w
 123    * @param h Specify the area of the window to render, in CSS
 124    * pixels. This is relative to the current scroll position.
 125    * @param scale The scale to render the window at. Use devicePixelRatio
 126    * to have comparable rendering to the OS.
 127    * @param backgroundColor The background color to use.
 128    *
 129    * This API can only be used in the parent process, as content processes
 130    * cannot access the rendering of out of process iframes. This API works
 131    * with remote and local frames.
 132    */
 133   [Throws]
 134   Promise<ImageBitmap> drawSnapshot(double x,
 135                                     double y,
 136                                     double w,
 137                                     double h,
 138                                     double scale,
 139                                     DOMString backgroundColor);
 140
 141   /**
 142    * The element which owns this frame loader.
 143    *
 144    * For example, if this is a frame loader for an <iframe>, this attribute
 145    * returns the iframe element.
 146    */
 147   [Pure]
 148   readonly attribute Element? ownerElement;
 149
 150
 151   /**
 152    * Cached childID of the ContentParent owning the TabParent in this frame
 153    * loader. This can be used to obtain the childID after the TabParent died.
 154    */
 155   [Pure]
 156   readonly attribute unsigned long long childID;
 157
 158   /**
 159    * Find out whether the owner content really is a mozbrowser. <xul:browser>
 160    * is not considered to be a mozbrowser frame.
 161    */
 162   [Pure]
 163   readonly attribute boolean ownerIsMozBrowserFrame;
 164
 165   /**
 166    * The last known width of the frame. Reading this property will not trigger
 167    * a reflow, and therefore may not reflect the current state of things. It
 168    * should only be used in asynchronous APIs where values are not guaranteed
 169    * to be up-to-date when received.
 170    */
 171   [Pure]
 172   readonly attribute unsigned long lazyWidth;
 173
 174   /**
 175    * The last known height of the frame. Reading this property will not trigger
 176    * a reflow, and therefore may not reflect the current state of things. It
 177    * should only be used in asynchronous APIs where values are not guaranteed
 178    * to be up-to-date when received.
 179    */
 180   [Pure]
 181   readonly attribute unsigned long lazyHeight;
 182
 183   /**
 184    * Is `true` if the frameloader is dead (destroy has been called on it)
 185    */
 186   [Pure]
 187   readonly attribute boolean isDead;
 188 };
 189
 190 /**
 191  * Interface for objects which represent a document that can be
 192  * serialized with nsIWebBrowserPersist.  This interface is
 193  * asynchronous because the actual document can be in another process
 194  * (e.g., if this object is a FrameLoader for an out-of-process
 195  * frame).
 196  *
 197  * XXXbz This method should really just return a Promise...
 198  *
 199  * @see nsIWebBrowserPersistDocumentReceiver
 200  * @see nsIWebBrowserPersistDocument
 201  * @see nsIWebBrowserPersist
 202  *
 203  * @param aOuterWindowID
 204  *        The outer window ID of the subframe we'd like to persist.
 205  *        If set at 0, WebBrowserPersistable will attempt to persist
 206  *        the top-level document. If the outer window ID is for a subframe
 207  *        that does not exist, or is not held beneath the WebBrowserPersistable,
 208  *        aRecv's onError method will be called with NS_ERROR_NO_CONTENT.
 209  * @param aRecv
 210  *        The nsIWebBrowserPersistDocumentReceiver is a callback that
 211  *        will be fired once the document is ready for persisting.
 212  */
 213 [NoInterfaceObject]
 214 interface WebBrowserPersistable
 215 {
 216   [Throws]
 217   void startPersistence(unsigned long long aOuterWindowID,
 218                         nsIWebBrowserPersistDocumentReceiver aRecv);
 219 };
 220
 221 FrameLoader implements WebBrowserPersistable;