dom/chrome-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 RemoteTab;
   9 interface URI;
  10 interface nsIDocShell;
  11 interface nsIPrintSettings;
  12 interface nsIWebBrowserPersistDocumentReceiver;
  13 interface nsIWebProgressListener;
  14
  15 [ChromeOnly,
  16  Exposed=Window]
  17 interface FrameLoader {
  18   /**
  19    * Get the docshell from the frame loader.
  20    */
  21   [GetterThrows]
  22   readonly attribute nsIDocShell? docShell;
  23
  24   /**
  25    * Get this frame loader's RemoteTab, if it has a remote frame.  Otherwise,
  26    * returns null.
  27    */
  28   readonly attribute RemoteTab? remoteTab;
  29
  30   /**
  31    * Get an nsILoadContext for the top-level docshell. For remote
  32    * frames, a shim is returned that contains private browsing and app
  33    * information.
  34    */
  35   readonly attribute LoadContext? loadContext;
  36
  37   /**
  38    * Get the root BrowsingContext within the frame.
  39    * This may be null immediately after creating a remote frame.
  40    */
  41   readonly attribute BrowsingContext? browsingContext;
  42
  43   /**
  44    * Find out whether the loader's frame is at too great a depth in
  45    * the frame tree.  This can be used to decide what operations may
  46    * or may not be allowed on the loader's docshell.
  47    */
  48   [Pure]
  49   readonly attribute boolean depthTooGreat;
  50
  51   /**
  52    * Find out whether the loader's frame is a remote frame.
  53    */
  54   readonly attribute boolean isRemoteFrame;
  55
  56   // Note, when frameloaders are swapped, also messageManagers are swapped.
  57   readonly attribute MessageSender? messageManager;
  58
  59   /**
  60    * Force a remote browser to recompute its dimension and screen position.
  61    */
  62   [Throws]
  63   undefined requestUpdatePosition();
  64
  65   /**
  66    * Force a TabStateFlush from native sessionStoreListeners.
  67    * Returns a promise that resolves when all session store data has been
  68    * flushed.
  69    */
  70   [NewObject]
  71   Promise<undefined> requestTabStateFlush();
  72
  73   /**
  74    * Force Epoch update in native sessionStoreListeners.
  75    */
  76   undefined requestEpochUpdate(unsigned long aEpoch);
  77
  78   /**
  79    * Request a session history update in native sessionStoreListeners.
  80    */
  81   undefined requestSHistoryUpdate();
  82
  83   /**
  84    * Creates a print preview document in this frame, or updates the existing
  85    * print preview document with new print settings.
  86    *
  87    * @param aPrintSettings The print settings to use to layout the print
  88    *   preview document.
  89    * @param aSourceBrowsingContext Optionally, the browsing context that
  90    *   contains the document from which the print preview is to be generated,
  91    *   which must be in the same process as the browsing context of the frame
  92    *   loader itself.
  93    *
  94    *   This should only be passed on the first call.  It should not be passed
  95    *   for any subsequent calls that are made to update the existing print
  96    *   preview document with a new print settings object.
  97    * @return A Promise that resolves with a PrintPreviewSuccessInfo on success.
  98    */
  99   [NewObject]
 100   Promise<unsigned long> printPreview(nsIPrintSettings aPrintSettings,
 101                                       BrowsingContext? aSourceBrowsingContext);
 102
 103   /**
 104    * Inform the print preview document that we're done with it.
 105    */
 106   undefined exitPrintPreview();
 107
 108   /**
 109    * The element which owns this frame loader.
 110    *
 111    * For example, if this is a frame loader for an <iframe>, this attribute
 112    * returns the iframe element.
 113    */
 114   [Pure]
 115   readonly attribute Element? ownerElement;
 116
 117
 118   /**
 119    * Cached childID of the ContentParent owning the RemoteTab in this frame
 120    * loader. This can be used to obtain the childID after the RemoteTab died.
 121    */
 122   [Pure]
 123   readonly attribute unsigned long long childID;
 124
 125   /**
 126    * Find out whether the owner content really is a mozbrowser. <xul:browser>
 127    * is not considered to be a mozbrowser frame.
 128    */
 129   [Pure]
 130   readonly attribute boolean ownerIsMozBrowserFrame;
 131
 132   /**
 133    * The last known width of the frame. Reading this property will not trigger
 134    * a reflow, and therefore may not reflect the current state of things. It
 135    * should only be used in asynchronous APIs where values are not guaranteed
 136    * to be up-to-date when received.
 137    */
 138   [Pure]
 139   readonly attribute unsigned long lazyWidth;
 140
 141   /**
 142    * The last known height of the frame. Reading this property will not trigger
 143    * a reflow, and therefore may not reflect the current state of things. It
 144    * should only be used in asynchronous APIs where values are not guaranteed
 145    * to be up-to-date when received.
 146    */
 147   [Pure]
 148   readonly attribute unsigned long lazyHeight;
 149
 150   /**
 151    * Is `true` if the frameloader is dead (destroy has been called on it)
 152    */
 153   [Pure]
 154   readonly attribute boolean isDead;
 155 };
 156
 157 /**
 158  * Interface for objects which represent a document that can be
 159  * serialized with nsIWebBrowserPersist.  This interface is
 160  * asynchronous because the actual document can be in another process
 161  * (e.g., if this object is a FrameLoader for an out-of-process
 162  * frame).
 163  *
 164  * @see nsIWebBrowserPersistDocumentReceiver
 165  * @see nsIWebBrowserPersistDocument
 166  * @see nsIWebBrowserPersist
 167  *
 168  * @param aContext
 169  *        The browsing context of the subframe we'd like to persist.
 170  *        If set to nullptr, WebBrowserPersistable will attempt to persist
 171  *        the top-level document. If the browsing context is for a subframe
 172  *        that is not held beneath the WebBrowserPersistable, aRecv's onError
 173  *        method will be called with NS_ERROR_NO_CONTENT.
 174  * @param aRecv
 175  *        The nsIWebBrowserPersistDocumentReceiver is a callback that
 176  *        will be fired once the document is ready for persisting.
 177  */
 178 interface mixin WebBrowserPersistable
 179 {
 180   [Throws]
 181   undefined startPersistence(BrowsingContext? aContext,
 182                              nsIWebBrowserPersistDocumentReceiver aRecv);
 183 };
 184
 185 enum PrintPreviewOrientation {
 186     "landscape",
 187     "portrait",
 188     "unspecified"
 189 };
 190
 191 /**
 192  * Interface for the object that's used to resolve the Promise returned from
 193  * FrameLoader.printPreview() if that method successfully creates the print
 194  * preview document/successfully updates it with new settings.
 195  */
 196 [GenerateConversionToJS]
 197 dictionary PrintPreviewSuccessInfo {
 198   /**
 199    * The total number of sheets of paper required to print, taking into account
 200    * the provided nsIPrintSettings.  This takes into account page range
 201    * selection, the pages-per-sheet, whether duplex printing is enabled, etc.
 202    */
 203   unsigned long sheetCount = 0;
 204
 205   /**
 206    * The total number of virtual pages, not taking into account page range
 207    * selection, the pages-per-sheet, whether duplex printing is enabled, etc.
 208    */
 209   unsigned long totalPageCount = 0;
 210
 211   /**
 212    * Whether the preview is empty because of page range selection.
 213    */
 214   boolean isEmpty = false;
 215
 216   /**
 217    * Whether the document or any subdocument has a selection that can be
 218    * printed.
 219    */
 220   boolean hasSelection = false;
 221
 222   /**
 223    * Whether the previewed document has a selection itself.
 224    */
 225   boolean hasSelfSelection = false;
 226
 227   /**
 228    * Specified orientation of the document, or "unspecified".
 229    */
 230   PrintPreviewOrientation orientation = "unspecified";
 231
 232   /**
 233    * Specified page width of the document in inches, or null if no @page size was specified.
 234    */
 235   float? pageWidth = null;
 236
 237   /**
 238    * Specified page height of the document in inches, or null if no @page size was specified.
 239    */
 240   float? pageHeight = null;
 241 };
 242
 243 FrameLoader includes WebBrowserPersistable;