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