dom/chrome-webidl/BrowsingContext.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
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 interface URI;
   7 interface nsIDocShell;
   8 interface nsISecureBrowserUI;
   9 interface nsISHEntry;
  10 interface nsIPrintSettings;
  11 interface nsIWebProgress;
  12
  13 interface mixin LoadContextMixin {
  14   readonly attribute WindowProxy? associatedWindow;
  15
  16   readonly attribute WindowProxy? topWindow;
  17
  18   readonly attribute Element? topFrameElement;
  19
  20   readonly attribute boolean isContent;
  21
  22   [SetterThrows]
  23   attribute boolean usePrivateBrowsing;
  24
  25   readonly attribute boolean useRemoteTabs;
  26
  27   readonly attribute boolean useRemoteSubframes;
  28
  29   [BinaryName="useTrackingProtectionWebIDL", SetterThrows]
  30   attribute boolean useTrackingProtection;
  31
  32   [NewObject, Throws]
  33   readonly attribute any originAttributes;
  34 };
  35
  36 /**
  37  * Allowed CSS display modes. This needs to be kept in
  38  * sync with similar values in ServoStyleConsts.h
  39  */
  40 enum DisplayMode {
  41   "browser",
  42   "minimal-ui",
  43   "standalone",
  44   "fullscreen",
  45 };
  46
  47 /**
  48  * CSS prefers-color-scheme values.
  49  */
  50 enum PrefersColorSchemeOverride {
  51   "none",
  52   "light",
  53   "dark",
  54 };
  55
  56 /**
  57  * CSS forced-colors values.
  58  */
  59 enum ForcedColorsOverride {
  60   "none",
  61   "active",
  62 };
  63
  64 /**
  65  * Allowed overrides of platform/pref default behaviour for touch events.
  66  */
  67 enum TouchEventsOverride {
  68   "disabled", // Force-disable touch events.
  69   "enabled", // Force-enable touch events.
  70   "none", // Don't override behaviour for touch events.
  71 };
  72
  73 [Exposed=Window, ChromeOnly]
  74 interface BrowsingContext {
  75   static BrowsingContext? get(unsigned long long aId);
  76
  77   static BrowsingContext? getFromWindow(WindowProxy window);
  78
  79   static BrowsingContext? getCurrentTopByBrowserId(unsigned long long aId);
  80
  81   sequence<BrowsingContext> getAllBrowsingContextsInSubtree();
  82
  83   readonly attribute DOMString name;
  84
  85   readonly attribute BrowsingContext? parent;
  86
  87   readonly attribute BrowsingContext top;
  88
  89   [Cached, Frozen, Pure]
  90   readonly attribute sequence<BrowsingContext> children;
  91
  92   readonly attribute nsIDocShell? docShell;
  93
  94   readonly attribute Element? embedderElement;
  95
  96   readonly attribute unsigned long long id;
  97
  98   readonly attribute BrowsingContext? opener;
  99
 100   readonly attribute BrowsingContextGroup group;
 101
 102   readonly attribute WindowProxy? window;
 103
 104   readonly attribute WindowContext? currentWindowContext;
 105
 106   readonly attribute WindowContext? parentWindowContext;
 107
 108   readonly attribute WindowContext? topWindowContext;
 109
 110   readonly attribute boolean ancestorsAreCurrent;
 111
 112   [SetterThrows] attribute [LegacyNullToEmptyString] DOMString customPlatform;
 113
 114   [SetterThrows] attribute [LegacyNullToEmptyString] DOMString customUserAgent;
 115
 116   readonly attribute DOMString embedderElementType;
 117
 118   readonly attribute boolean createdDynamically;
 119
 120   readonly attribute boolean isInBFCache;
 121
 122   readonly attribute boolean isDiscarded;
 123
 124   /**
 125    * The sandbox flags on the browsing context. These reflect the value of the
 126    * sandbox attribute of the associated IFRAME or CSP-protectable content, if
 127    * existent. See the HTML5 spec for more details.
 128    * These flags on the browsing context reflect the current state of the
 129    * sandbox attribute, which is modifiable. They are only used when loading new
 130    * content, sandbox flags are also immutably set on the document when it is
 131    * loaded.
 132    * The sandbox flags of a document depend on the sandbox flags on its
 133    * browsing context and of its parent document, if any.
 134    * See nsSandboxFlags.h for the possible flags.
 135    */
 136   [SetterThrows] attribute unsigned long sandboxFlags;
 137
 138   /**
 139    * Whether the BrowsingContext is active. That is, whether it's in a
 140    * foreground tab, and not minimized or fully occluded otherwise.
 141    */
 142   readonly attribute boolean isActive;
 143
 144   /**
 145    * When set to true all channels in this browsing context or its children will report navigator.onLine = false,
 146    * and HTTP requests created from these browsing context will fail with NS_ERROR_OFFLINE.
 147    */
 148   [SetterThrows] attribute boolean forceOffline;
 149
 150   /**
 151    * Sets whether this is an app tab. Non-same-origin link navigations from app
 152    * tabs may be forced to open in new contexts, rather than in the same context.
 153    */
 154   [SetterThrows] attribute boolean isAppTab;
 155
 156   /**
 157    * Sets whether this is BC has siblings **at the toplevel** (e.g. in a tabbed
 158    * browser environment). Used to determine if web content can resize the top
 159    * window. Never set correctly for non-top BCs.
 160    */
 161   [SetterThrows] attribute boolean hasSiblings;
 162
 163   // The inRDMPane flag indicates whether or not Responsive Design Mode is
 164   // active for the browsing context.
 165   [SetterThrows] attribute boolean inRDMPane;
 166
 167   [SetterThrows] attribute float fullZoom;
 168
 169   [SetterThrows] attribute float textZoom;
 170
 171   // Override the dots-per-CSS-pixel scaling factor in this BrowsingContext
 172   // and all of its descendants. May only be set on the top BC, and should
 173   // only be set from the parent process.
 174   //
 175   // A value of 0.0 causes us to use the global default scaling factor.
 176   //
 177   // NOTE that this override only affects a few minor things (the value exposed
 178   // to devicePixelRatio and some media queries in content, and responsive
 179   // image selection). Most notably, it does _not_ affect rendering.
 180   //
 181   // It is intended for RDM, and is probably not what you want in other cases.
 182   // If you want to change the actual device pixel ratio that rendering code
 183   // uses, you probably want to change the fullZoom.
 184   [SetterThrows] attribute float overrideDPPX;
 185
 186   [SetterThrows] attribute boolean suspendMediaWhenInactive;
 187
 188   // Default value for nsIDocumentViewer::authorStyleDisabled in any new
 189   // browsing contexts created as a descendant of this one.
 190   //
 191   // Valid only for top browsing contexts.
 192   [SetterThrows] attribute boolean authorStyleDisabledDefault;
 193
 194   /**
 195    * Whether this docshell should save entries in global history.
 196    */
 197   [SetterThrows] attribute boolean useGlobalHistory;
 198
 199   // Extension to give chrome JS the ability to set the window screen
 200   // orientation while in RDM.
 201   [Throws] undefined setRDMPaneOrientation(OrientationType type, float rotationAngle);
 202
 203   // Extension to give chrome JS the ability to set a maxTouchPoints override
 204   // while in RDM.
 205   [Throws] undefined setRDMPaneMaxTouchPoints(octet maxTouchPoints);
 206
 207   // The watchedByDevTools flag indicates whether or not DevTools are currently
 208   // debugging this browsing context.
 209   [SetterThrows] attribute boolean watchedByDevTools;
 210
 211   // Enable some service workers testing features, for DevTools.
 212   [SetterThrows] attribute boolean serviceWorkersTestingEnabled;
 213
 214   // Enable media query medium override, for DevTools.
 215   [SetterThrows] attribute DOMString mediumOverride;
 216
 217   // Color-scheme simulation, for DevTools.
 218   [SetterThrows] attribute PrefersColorSchemeOverride prefersColorSchemeOverride;
 219
 220   // Forced-colors simulation, for DevTools
 221   [SetterThrows] attribute ForcedColorsOverride forcedColorsOverride;
 222
 223   /**
 224    * A unique identifier for the browser element that is hosting this
 225    * BrowsingContext tree. Every BrowsingContext in the element's tree will
 226    * return the same ID in all processes and it will remain stable regardless of
 227    * process changes. When a browser element's frameloader is switched to
 228    * another browser element this ID will remain the same but hosted under the
 229    * under the new browser element.
 230    */
 231   [SetterThrows] attribute unsigned long long browserId;
 232
 233   [SetterThrows] attribute DisplayMode displayMode;
 234
 235   /**
 236    * This allows chrome to override the default choice of whether touch events
 237    * are available in a specific BrowsingContext and its descendents.
 238    */
 239   readonly attribute TouchEventsOverride touchEventsOverride;
 240
 241   /**
 242    * Returns true if the top-level BrowsingContext has been configured to
 243    * default-target user-initiated link clicks to _blank.
 244    */
 245   readonly attribute boolean targetTopLevelLinkClicksToBlank;
 246
 247   /**
 248    * Partially determines whether script execution is allowed in this
 249    * BrowsingContext. Script execution will be permitted only if this
 250    * attribute is true and script execution is allowed in the parent
 251    * WindowContext.
 252    *
 253    * May only be set in the parent process.
 254    */
 255   [SetterThrows] attribute boolean allowJavascript;
 256
 257   /**
 258    * Determines whether we're forcing a desktop-mode viewport. Only settable in
 259    * the top browsing context from the parent process.
 260    */
 261   [SetterThrows] attribute boolean forceDesktopViewport;
 262
 263   /*
 264    * Default load flags (as defined in nsIRequest) that will be set on all
 265    * requests made by this BrowsingContext.
 266    */
 267   [SetterThrows] attribute long defaultLoadFlags;
 268
 269   /**
 270    * The nsID of the browsing context in the session history.
 271    */
 272   [NewObject, Throws]
 273   readonly attribute any historyID;
 274
 275   readonly attribute ChildSHistory? childSessionHistory;
 276
 277   // Resets the location change rate limit. Used for testing.
 278   undefined resetNavigationRateLimit();
 279
 280   readonly attribute long childOffset;
 281 };
 282
 283 BrowsingContext includes LoadContextMixin;
 284
 285 [Exposed=Window, ChromeOnly]
 286 interface CanonicalBrowsingContext : BrowsingContext {
 287   sequence<WindowGlobalParent> getWindowGlobals();
 288
 289   readonly attribute WindowGlobalParent? currentWindowGlobal;
 290
 291   readonly attribute WindowProxy? topChromeWindow;
 292
 293   // XXX(nika): This feels kinda hacky, but will do for now while we don't
 294   // synchronously create WindowGlobalParent. It can throw if somehow the
 295   // content process has died.
 296   [Throws]
 297   readonly attribute UTF8String? currentRemoteType;
 298
 299   readonly attribute WindowGlobalParent? embedderWindowGlobal;
 300
 301   undefined notifyStartDelayedAutoplayMedia();
 302   [Throws] undefined notifyMediaMutedChanged(boolean muted);
 303
 304   readonly attribute nsISecureBrowserUI? secureBrowserUI;
 305
 306   /**
 307    * Returns an nsIWebProgress object for this BrowsingContext, if this
 308    * is a top-level content BC.
 309    *
 310    * Progress listeners attached to this will get notifications filtered by
 311    * nsBrowserStatusFilter, and don't get any notifications from sub frames.
 312    */
 313   readonly attribute nsIWebProgress? webProgress;
 314
 315   static unsigned long countSiteOrigins(sequence<BrowsingContext> roots);
 316
 317   /**
 318    * Loads a given URI.  This will give priority to loading the requested URI
 319    * in the object implementing this interface.  If it can't be loaded here
 320    * however, the URI dispatcher will go through its normal process of content
 321    * loading.
 322    *
 323    * @param aURI
 324    *        The URI to load.  No fixup will be performed on this URI.
 325    * @param aLoadURIOptions
 326    *        A JSObject defined in LoadURIOptions.webidl holding info like e.g.
 327    *        the triggeringPrincipal, the referrer info.
 328    */
 329   [Throws]
 330   undefined loadURI(URI aURI, optional LoadURIOptions aOptions = {});
 331
 332   /**
 333    * Like `loadURI` but takes a DOMString instead. This will use nsIURIFixup
 334    * to "fix up" the input if it doesn't parse as a string. If an existing
 335    * DOM URL or nsIURI object is available to you, prefer using `loadURI`
 336    * directly.
 337    *
 338    * @param aURI
 339    *        The URI to load.  For HTTP and FTP URLs and possibly others,
 340    *        characters above U+007F will be converted to UTF-8 and then URL-
 341    *        escaped per the rules of RFC 2396.
 342    * @param aLoadURIOptions
 343    *        A JSObject defined in LoadURIOptions.webidl holding info like e.g.
 344    *        the triggeringPrincipal, the referrer info.
 345    */
 346   [Throws]
 347   undefined fixupAndLoadURIString(DOMString aURI, optional LoadURIOptions aOptions = {});
 348
 349    /**
 350     * Print the current document.
 351     *
 352     * @param aOuterWindowID the ID of the outer window to print
 353     * @param aPrintSettings print settings to use; printSilent can be
 354     *                       set to prevent prompting.
 355     * @return A Promise that resolves once printing is finished.
 356     */
 357   [NewObject, BinaryName="printJS"]
 358   Promise<undefined> print(nsIPrintSettings aPrintSettings);
 359
 360   /**
 361    * These methods implement the nsIWebNavigation methods of the same names
 362    */
 363   undefined goBack(optional long aCancelContentJSEpoch, optional boolean aRequireUserInteraction = false, optional boolean aUserActivation = false);
 364   undefined goForward(optional long aCancelContentJSEpoch, optional boolean aRequireUserInteraction  = false, optional boolean aUserActivation = false);
 365   undefined goToIndex(long aIndex, optional long aCancelContentJSEpoch, optional boolean aUserActivation = false);
 366   undefined reload(unsigned long aReloadFlags);
 367   undefined stop(unsigned long aStopFlags);
 368
 369   readonly attribute nsISHistory? sessionHistory;
 370   readonly attribute nsISHEntry? activeSessionHistoryEntry;
 371
 372   readonly attribute MediaController? mediaController;
 373
 374   undefined resetScalingZoom();
 375
 376   // The current URI loaded in this BrowsingContext according to nsDocShell.
 377   // This may not match the current window global's document URI in some cases.
 378   readonly attribute URI? currentURI;
 379
 380   undefined clearRestoreState();
 381
 382   // Force this browsing context, which must correspond to an app window, to
 383   // be active regardless of the window being minimized or fully occluded.
 384   [SetterThrows] attribute boolean forceAppWindowActive;
 385
 386   // @see BrowsingContext.isActive.
 387   [SetterThrows] attribute boolean isActive;
 388
 389   /**
 390    * This allows chrome to override the default choice of whether touch events
 391    * are available in a specific BrowsingContext and its descendents.
 392    */
 393   [SetterThrows] inherit attribute TouchEventsOverride touchEventsOverride;
 394
 395   /**
 396    * Set to true to configure the top-level BrowsingContext to default-target
 397    * user-initiated link clicks to _blank.
 398    */
 399   [SetterThrows] inherit attribute boolean targetTopLevelLinkClicksToBlank;
 400
 401   /**
 402    * Set the cross-group opener of this BrowsingContext. This tracks the opener
 403    * of a browsing context regardless if that context is opened using noopener.
 404    *
 405    * This value will be automatically set for documents created using
 406    * `window.open`.
 407    */
 408   [SetterThrows]
 409   attribute CanonicalBrowsingContext? crossGroupOpener;
 410
 411   readonly attribute boolean isReplaced;
 412
 413
 414   /**
 415    * Notify APZ to start autoscrolling.
 416    *
 417    * (aAnchorX, aAnchorY) are the coordinates of the autoscroll anchor, in
 418    *                      device coordinates relative to the screen.
 419    * aScrollId and aPresShellId identify the scroll frame that content chose to
 420    *                            scroll.
 421    *
 422    * Returns whether we were successfully able to notify APZ.
 423    * If this function returns true, APZ (which may live in another process) may
 424    * still reject the autoscroll, but it's then APZ's responsibility to notify
 425    * content via an "autoscroll-rejected-by-apz" message.
 426    */
 427   boolean startApzAutoscroll(float aAnchorX, float aAnchorY,
 428                              unsigned long long aScrollId,
 429                              unsigned long aPresShellId);
 430
 431   /**
 432    * Notify APZ to stop autoscrolling.
 433    */
 434   undefined stopApzAutoscroll(unsigned long long aScrollId,
 435                               unsigned long aPresShellId);
 436
 437   readonly attribute nsISHEntry? mostRecentLoadingSessionHistoryEntry;
 438
 439   /**
 440    * Indicates if the embedder element or an ancestor has hidden
 441    * visibility, or no frame.
 442    */
 443   readonly attribute boolean isUnderHiddenEmbedderElement;
 444
 445   /**
 446    * Indicates whether opening a modal picker is permitted.
 447    */
 448   readonly attribute boolean canOpenModalPicker;
 449 };
 450
 451 [Exposed=Window, ChromeOnly]
 452 interface BrowsingContextGroup {
 453   sequence<BrowsingContext> getToplevels();
 454
 455   readonly attribute unsigned long long id;
 456 };