FrameLoader.webidl (7397B)
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 * The last known width of the frame. Reading this property will not trigger 127 * a reflow, and therefore may not reflect the current state of things. It 128 * should only be used in asynchronous APIs where values are not guaranteed 129 * to be up-to-date when received. 130 */ 131 [Pure] 132 readonly attribute unsigned long lazyWidth; 133 134 /** 135 * The last known height of the frame. Reading this property will not trigger 136 * a reflow, and therefore may not reflect the current state of things. It 137 * should only be used in asynchronous APIs where values are not guaranteed 138 * to be up-to-date when received. 139 */ 140 [Pure] 141 readonly attribute unsigned long lazyHeight; 142 143 /** 144 * Is `true` if the frameloader is dead (destroy has been called on it) 145 */ 146 [Pure] 147 readonly attribute boolean isDead; 148 }; 149 150 /** 151 * Interface for objects which represent a document that can be 152 * serialized with nsIWebBrowserPersist. This interface is 153 * asynchronous because the actual document can be in another process 154 * (e.g., if this object is a FrameLoader for an out-of-process 155 * frame). 156 * 157 * @see nsIWebBrowserPersistDocumentReceiver 158 * @see nsIWebBrowserPersistDocument 159 * @see nsIWebBrowserPersist 160 * 161 * @param aContext 162 * The browsing context of the subframe we'd like to persist. 163 * If set to nullptr, WebBrowserPersistable will attempt to persist 164 * the top-level document. If the browsing context is for a subframe 165 * that is not held beneath the WebBrowserPersistable, aRecv's onError 166 * method will be called with NS_ERROR_NO_CONTENT. 167 * @param aRecv 168 * The nsIWebBrowserPersistDocumentReceiver is a callback that 169 * will be fired once the document is ready for persisting. 170 */ 171 interface mixin WebBrowserPersistable 172 { 173 [Throws] 174 undefined startPersistence(BrowsingContext? aContext, 175 nsIWebBrowserPersistDocumentReceiver aRecv); 176 }; 177 178 enum PrintPreviewOrientation { 179 "landscape", 180 "portrait", 181 "unspecified" 182 }; 183 184 /** 185 * Interface for the object that's used to resolve the Promise returned from 186 * FrameLoader.printPreview() if that method successfully creates the print 187 * preview document/successfully updates it with new settings. 188 */ 189 [GenerateConversionToJS] 190 dictionary PrintPreviewSuccessInfo { 191 /** 192 * The total number of sheets of paper required to print, taking into account 193 * the provided nsIPrintSettings. This takes into account page range 194 * selection, the pages-per-sheet, whether duplex printing is enabled, etc. 195 */ 196 unsigned long sheetCount = 0; 197 198 /** 199 * The total number of virtual pages, not taking into account page range 200 * selection, the pages-per-sheet, whether duplex printing is enabled, etc. 201 */ 202 unsigned long totalPageCount = 0; 203 204 /** 205 * Whether the preview is empty because of page range selection. 206 */ 207 boolean isEmpty = false; 208 209 /** 210 * Whether the document or any subdocument has a selection that can be 211 * printed. 212 */ 213 boolean hasSelection = false; 214 215 /** 216 * Whether the previewed document has a selection itself. 217 */ 218 boolean hasSelfSelection = false; 219 220 /** 221 * Specified orientation of the document, or "unspecified". 222 */ 223 PrintPreviewOrientation orientation = "unspecified"; 224 225 /** 226 * Specified page width of the document in inches, or null if no @page size was specified. 227 */ 228 float? pageWidth = null; 229 230 /** 231 * Specified page height of the document in inches, or null if no @page size was specified. 232 */ 233 float? pageHeight = null; 234 }; 235 236 FrameLoader includes WebBrowserPersistable;