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
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
8 interface nsISecureBrowserUI;
10 interface nsIPrintSettings;
11 interface nsIWebProgress;
13 interface mixin LoadContextMixin {
14 readonly attribute WindowProxy? associatedWindow;
16 readonly attribute WindowProxy? topWindow;
18 readonly attribute Element? topFrameElement;
20 readonly attribute boolean isContent;
23 attribute boolean usePrivateBrowsing;
25 readonly attribute boolean useRemoteTabs;
27 readonly attribute boolean useRemoteSubframes;
29 [BinaryName="useTrackingProtectionWebIDL", SetterThrows]
30 attribute boolean useTrackingProtection;
33 readonly attribute any originAttributes;
37 * Allowed CSS display modes. This needs to be kept in
38 * sync with similar values in ServoStyleConsts.h
48 * CSS prefers-color-scheme values.
50 enum PrefersColorSchemeOverride {
57 * Allowed overrides of platform/pref default behaviour for touch events.
59 enum TouchEventsOverride {
60 "disabled", // Force-disable touch events.
61 "enabled", // Force-enable touch events.
62 "none", // Don't override behaviour for touch events.
65 [Exposed=Window, ChromeOnly]
66 interface BrowsingContext {
67 static BrowsingContext? get(unsigned long long aId);
69 static BrowsingContext? getFromWindow(WindowProxy window);
71 static BrowsingContext? getCurrentTopByBrowserId(unsigned long long aId);
73 sequence<BrowsingContext> getAllBrowsingContextsInSubtree();
75 readonly attribute DOMString name;
77 readonly attribute BrowsingContext? parent;
79 readonly attribute BrowsingContext top;
81 [Cached, Frozen, Pure]
82 readonly attribute sequence<BrowsingContext> children;
84 readonly attribute nsIDocShell? docShell;
86 readonly attribute Element? embedderElement;
88 readonly attribute unsigned long long id;
90 readonly attribute BrowsingContext? opener;
92 readonly attribute BrowsingContextGroup group;
94 readonly attribute WindowProxy? window;
96 readonly attribute WindowContext? currentWindowContext;
98 readonly attribute WindowContext? parentWindowContext;
100 readonly attribute WindowContext? topWindowContext;
102 readonly attribute boolean ancestorsAreCurrent;
104 [SetterThrows] attribute [LegacyNullToEmptyString] DOMString customPlatform;
106 [SetterThrows] attribute [LegacyNullToEmptyString] DOMString customUserAgent;
108 readonly attribute DOMString embedderElementType;
110 readonly attribute boolean createdDynamically;
112 readonly attribute boolean isInBFCache;
114 readonly attribute boolean isDiscarded;
117 * The sandbox flags on the browsing context. These reflect the value of the
118 * sandbox attribute of the associated IFRAME or CSP-protectable content, if
119 * existent. See the HTML5 spec for more details.
120 * These flags on the browsing context reflect the current state of the
121 * sandbox attribute, which is modifiable. They are only used when loading new
122 * content, sandbox flags are also immutably set on the document when it is
124 * The sandbox flags of a document depend on the sandbox flags on its
125 * browsing context and of its parent document, if any.
126 * See nsSandboxFlags.h for the possible flags.
128 [SetterThrows] attribute unsigned long sandboxFlags;
130 [SetterThrows] attribute boolean isActive;
133 * When set to true all channels in this browsing context or its children will report navigator.onLine = false,
134 * and HTTP requests created from these browsing context will fail with NS_ERROR_OFFLINE.
136 [SetterThrows] attribute boolean forceOffline;
139 * Sets whether this is an app tab. Non-same-origin link navigations from app
140 * tabs may be forced to open in new contexts, rather than in the same context.
142 [SetterThrows] attribute boolean isAppTab;
145 * Sets whether this is BC has siblings **at the toplevel** (e.g. in a tabbed
146 * browser environment). Used to determine if web content can resize the top
147 * window. Never set correctly for non-top BCs.
149 [SetterThrows] attribute boolean hasSiblings;
151 // The inRDMPane flag indicates whether or not Responsive Design Mode is
152 // active for the browsing context.
153 [SetterThrows] attribute boolean inRDMPane;
155 [SetterThrows] attribute float fullZoom;
157 [SetterThrows] attribute float textZoom;
159 // Override the dots-per-CSS-pixel scaling factor in this BrowsingContext
160 // and all of its descendants. May only be set on the top BC, and should
161 // only be set from the parent process.
163 // A value of 0.0 causes us to use the global default scaling factor.
165 // NOTE that this override only affects a few minor things (the value exposed
166 // to devicePixelRatio and some media queries in content, and responsive
167 // image selection). Most notably, it does _not_ affect rendering.
169 // It is intended for RDM, and is probably not what you want in other cases.
170 // If you want to change the actual device pixel ratio that rendering code
171 // uses, you probably want to change the fullZoom.
172 [SetterThrows] attribute float overrideDPPX;
174 [SetterThrows] attribute boolean suspendMediaWhenInactive;
176 // Default value for nsIDocumentViewer::authorStyleDisabled in any new
177 // browsing contexts created as a descendant of this one.
179 // Valid only for top browsing contexts.
180 [SetterThrows] attribute boolean authorStyleDisabledDefault;
183 * Whether this docshell should save entries in global history.
185 [SetterThrows] attribute boolean useGlobalHistory;
187 // Extension to give chrome JS the ability to set the window screen
188 // orientation while in RDM.
189 [Throws] undefined setRDMPaneOrientation(OrientationType type, float rotationAngle);
191 // Extension to give chrome JS the ability to set a maxTouchPoints override
193 [Throws] undefined setRDMPaneMaxTouchPoints(octet maxTouchPoints);
195 // The watchedByDevTools flag indicates whether or not DevTools are currently
196 // debugging this browsing context.
197 [SetterThrows] attribute boolean watchedByDevTools;
199 // Enable some service workers testing features, for DevTools.
200 [SetterThrows] attribute boolean serviceWorkersTestingEnabled;
202 // Enable media query medium override, for DevTools.
203 [SetterThrows] attribute DOMString mediumOverride;
205 // Color-scheme simulation, for DevTools.
206 [SetterThrows] attribute PrefersColorSchemeOverride prefersColorSchemeOverride;
209 * A unique identifier for the browser element that is hosting this
210 * BrowsingContext tree. Every BrowsingContext in the element's tree will
211 * return the same ID in all processes and it will remain stable regardless of
212 * process changes. When a browser element's frameloader is switched to
213 * another browser element this ID will remain the same but hosted under the
214 * under the new browser element.
216 [SetterThrows] attribute unsigned long long browserId;
218 [SetterThrows] attribute DisplayMode displayMode;
221 * This allows chrome to override the default choice of whether touch events
222 * are available in a specific BrowsingContext and its descendents.
224 readonly attribute TouchEventsOverride touchEventsOverride;
227 * Returns true if the top-level BrowsingContext has been configured to
228 * default-target user-initiated link clicks to _blank.
230 readonly attribute boolean targetTopLevelLinkClicksToBlank;
233 * Partially determines whether script execution is allowed in this
234 * BrowsingContext. Script execution will be permitted only if this
235 * attribute is true and script execution is allowed in the parent
238 * May only be set in the parent process.
240 [SetterThrows] attribute boolean allowJavascript;
243 * Determines whether we're forcing a desktop-mode viewport. Only settable in
244 * the top browsing context from the parent process.
246 [SetterThrows] attribute boolean forceDesktopViewport;
249 * Default load flags (as defined in nsIRequest) that will be set on all
250 * requests made by this BrowsingContext.
252 [SetterThrows] attribute long defaultLoadFlags;
255 * The nsID of the browsing context in the session history.
258 readonly attribute any historyID;
260 readonly attribute ChildSHistory? childSessionHistory;
262 // Resets the location change rate limit. Used for testing.
263 undefined resetLocationChangeRateLimit();
265 readonly attribute long childOffset;
268 BrowsingContext includes LoadContextMixin;
270 [Exposed=Window, ChromeOnly]
271 interface CanonicalBrowsingContext : BrowsingContext {
272 sequence<WindowGlobalParent> getWindowGlobals();
274 readonly attribute WindowGlobalParent? currentWindowGlobal;
276 readonly attribute WindowProxy? topChromeWindow;
278 // XXX(nika): This feels kinda hacky, but will do for now while we don't
279 // synchronously create WindowGlobalParent. It can throw if somehow the
280 // content process has died.
282 readonly attribute UTF8String? currentRemoteType;
284 readonly attribute WindowGlobalParent? embedderWindowGlobal;
286 undefined notifyStartDelayedAutoplayMedia();
287 [Throws] undefined notifyMediaMutedChanged(boolean muted);
289 readonly attribute nsISecureBrowserUI? secureBrowserUI;
292 * Returns an nsIWebProgress object for this BrowsingContext, if this
293 * is a top-level content BC.
295 * Progress listeners attached to this will get notifications filtered by
296 * nsBrowserStatusFilter, and don't get any notifications from sub frames.
298 readonly attribute nsIWebProgress? webProgress;
300 static unsigned long countSiteOrigins(sequence<BrowsingContext> roots);
303 * Loads a given URI. This will give priority to loading the requested URI
304 * in the object implementing this interface. If it can't be loaded here
305 * however, the URI dispatcher will go through its normal process of content
309 * The URI to load. No fixup will be performed on this URI.
310 * @param aLoadURIOptions
311 * A JSObject defined in LoadURIOptions.webidl holding info like e.g.
312 * the triggeringPrincipal, the referrer info.
315 undefined loadURI(URI aURI, optional LoadURIOptions aOptions = {});
318 * Like `loadURI` but takes a DOMString instead. This will use nsIURIFixup
319 * to "fix up" the input if it doesn't parse as a string. If an existing
320 * DOM URL or nsIURI object is available to you, prefer using `loadURI`
324 * The URI to load. For HTTP and FTP URLs and possibly others,
325 * characters above U+007F will be converted to UTF-8 and then URL-
326 * escaped per the rules of RFC 2396.
327 * @param aLoadURIOptions
328 * A JSObject defined in LoadURIOptions.webidl holding info like e.g.
329 * the triggeringPrincipal, the referrer info.
332 undefined fixupAndLoadURIString(DOMString aURI, optional LoadURIOptions aOptions = {});
335 * Print the current document.
337 * @param aOuterWindowID the ID of the outer window to print
338 * @param aPrintSettings print settings to use; printSilent can be
339 * set to prevent prompting.
340 * @return A Promise that resolves once printing is finished.
342 [NewObject, BinaryName="printJS"]
343 Promise<undefined> print(nsIPrintSettings aPrintSettings);
346 * These methods implement the nsIWebNavigation methods of the same names
348 undefined goBack(optional long aCancelContentJSEpoch, optional boolean aRequireUserInteraction = false, optional boolean aUserActivation = false);
349 undefined goForward(optional long aCancelContentJSEpoch, optional boolean aRequireUserInteraction = false, optional boolean aUserActivation = false);
350 undefined goToIndex(long aIndex, optional long aCancelContentJSEpoch, optional boolean aUserActivation = false);
351 undefined reload(unsigned long aReloadFlags);
352 undefined stop(unsigned long aStopFlags);
354 readonly attribute nsISHistory? sessionHistory;
355 readonly attribute nsISHEntry? activeSessionHistoryEntry;
357 readonly attribute MediaController? mediaController;
359 undefined resetScalingZoom();
361 // The current URI loaded in this BrowsingContext according to nsDocShell.
362 // This may not match the current window global's document URI in some cases.
363 readonly attribute URI? currentURI;
365 undefined clearRestoreState();
367 // Force this browsing context, which must correspond to an app window, to
368 // be active regardless of the window being minimized or fully occluded.
369 [SetterThrows] attribute boolean forceAppWindowActive;
372 * This allows chrome to override the default choice of whether touch events
373 * are available in a specific BrowsingContext and its descendents.
375 [SetterThrows] inherit attribute TouchEventsOverride touchEventsOverride;
378 * Set to true to configure the top-level BrowsingContext to default-target
379 * user-initiated link clicks to _blank.
381 [SetterThrows] inherit attribute boolean targetTopLevelLinkClicksToBlank;
384 * Set the cross-group opener of this BrowsingContext. This is used to
385 * retarget the download dialog to an opener window, and close this
386 * BrowsingContext, if the first load in a newly created BrowsingContext is a
389 * This value will be automatically set for documents created using
393 undefined setCrossGroupOpener(CanonicalBrowsingContext crossGroupOpener);
395 readonly attribute boolean isReplaced;
399 * Notify APZ to start autoscrolling.
401 * (aAnchorX, aAnchorY) are the coordinates of the autoscroll anchor, in
402 * device coordinates relative to the screen.
403 * aScrollId and aPresShellId identify the scroll frame that content chose to
406 * Returns whether we were successfully able to notify APZ.
407 * If this function returns true, APZ (which may live in another process) may
408 * still reject the autoscroll, but it's then APZ's responsibility to notify
409 * content via an "autoscroll-rejected-by-apz" message.
411 boolean startApzAutoscroll(float aAnchorX, float aAnchorY,
412 unsigned long long aScrollId,
413 unsigned long aPresShellId);
416 * Notify APZ to stop autoscrolling.
418 undefined stopApzAutoscroll(unsigned long long aScrollId,
419 unsigned long aPresShellId);
421 readonly attribute nsISHEntry? mostRecentLoadingSessionHistoryEntry;
424 * Indicates if the embedder element or an ancestor has hidden
425 * visibility, or no frame.
427 readonly attribute boolean isUnderHiddenEmbedderElement;
430 [Exposed=Window, ChromeOnly]
431 interface BrowsingContextGroup {
432 sequence<BrowsingContext> getToplevels();
434 readonly attribute unsigned long long id;