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   [SetterThrows] attribute boolean isActive;
 131
 132   /**
 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.
 135    */
 136   [SetterThrows] attribute boolean forceOffline;
 137
 138   /**
 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.
 141    */
 142   [SetterThrows] attribute boolean isAppTab;
 143
 144   /**
 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.
 148    */
 149   [SetterThrows] attribute boolean hasSiblings;
 150
 151   // The inRDMPane flag indicates whether or not Responsive Design Mode is
 152   // active for the browsing context.
 153   [SetterThrows] attribute boolean inRDMPane;
 154
 155   [SetterThrows] attribute float fullZoom;
 156
 157   [SetterThrows] attribute float textZoom;
 158
 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.
 162   //
 163   // A value of 0.0 causes us to use the global default scaling factor.
 164   //
 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.
 168   //
 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;
 173
 174   [SetterThrows] attribute boolean suspendMediaWhenInactive;
 175
 176   // Default value for nsIDocumentViewer::authorStyleDisabled in any new
 177   // browsing contexts created as a descendant of this one.
 178   //
 179   // Valid only for top browsing contexts.
 180   [SetterThrows] attribute boolean authorStyleDisabledDefault;
 181
 182   /**
 183    * Whether this docshell should save entries in global history.
 184    */
 185   [SetterThrows] attribute boolean useGlobalHistory;
 186
 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);
 190
 191   // Extension to give chrome JS the ability to set a maxTouchPoints override
 192   // while in RDM.
 193   [Throws] undefined setRDMPaneMaxTouchPoints(octet maxTouchPoints);
 194
 195   // The watchedByDevTools flag indicates whether or not DevTools are currently
 196   // debugging this browsing context.
 197   [SetterThrows] attribute boolean watchedByDevTools;
 198
 199   // Enable some service workers testing features, for DevTools.
 200   [SetterThrows] attribute boolean serviceWorkersTestingEnabled;
 201
 202   // Enable media query medium override, for DevTools.
 203   [SetterThrows] attribute DOMString mediumOverride;
 204
 205   // Color-scheme simulation, for DevTools.
 206   [SetterThrows] attribute PrefersColorSchemeOverride prefersColorSchemeOverride;
 207
 208   /**
 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.
 215    */
 216   [SetterThrows] attribute unsigned long long browserId;
 217
 218   [SetterThrows] attribute DisplayMode displayMode;
 219
 220   /**
 221    * This allows chrome to override the default choice of whether touch events
 222    * are available in a specific BrowsingContext and its descendents.
 223    */
 224   readonly attribute TouchEventsOverride touchEventsOverride;
 225
 226   /**
 227    * Returns true if the top-level BrowsingContext has been configured to
 228    * default-target user-initiated link clicks to _blank.
 229    */
 230   readonly attribute boolean targetTopLevelLinkClicksToBlank;
 231
 232   /**
 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
 236    * WindowContext.
 237    *
 238    * May only be set in the parent process.
 239    */
 240   [SetterThrows] attribute boolean allowJavascript;
 241
 242   /**
 243    * Determines whether we're forcing a desktop-mode viewport. Only settable in
 244    * the top browsing context from the parent process.
 245    */
 246   [SetterThrows] attribute boolean forceDesktopViewport;
 247
 248   /*
 249    * Default load flags (as defined in nsIRequest) that will be set on all
 250    * requests made by this BrowsingContext.
 251    */
 252   [SetterThrows] attribute long defaultLoadFlags;
 253
 254   /**
 255    * The nsID of the browsing context in the session history.
 256    */
 257   [NewObject, Throws]
 258   readonly attribute any historyID;
 259
 260   readonly attribute ChildSHistory? childSessionHistory;
 261
 262   // Resets the location change rate limit. Used for testing.
 263   undefined resetLocationChangeRateLimit();
 264
 265   readonly attribute long childOffset;
 266 };
 267
 268 BrowsingContext includes LoadContextMixin;
 269
 270 [Exposed=Window, ChromeOnly]
 271 interface CanonicalBrowsingContext : BrowsingContext {
 272   sequence<WindowGlobalParent> getWindowGlobals();
 273
 274   readonly attribute WindowGlobalParent? currentWindowGlobal;
 275
 276   readonly attribute WindowProxy? topChromeWindow;
 277
 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.
 281   [Throws]
 282   readonly attribute UTF8String? currentRemoteType;
 283
 284   readonly attribute WindowGlobalParent? embedderWindowGlobal;
 285
 286   undefined notifyStartDelayedAutoplayMedia();
 287   [Throws] undefined notifyMediaMutedChanged(boolean muted);
 288
 289   readonly attribute nsISecureBrowserUI? secureBrowserUI;
 290
 291   /**
 292    * Returns an nsIWebProgress object for this BrowsingContext, if this
 293    * is a top-level content BC.
 294    *
 295    * Progress listeners attached to this will get notifications filtered by
 296    * nsBrowserStatusFilter, and don't get any notifications from sub frames.
 297    */
 298   readonly attribute nsIWebProgress? webProgress;
 299
 300   static unsigned long countSiteOrigins(sequence<BrowsingContext> roots);
 301
 302   /**
 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
 306    * loading.
 307    *
 308    * @param aURI
 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.
 313    */
 314   [Throws]
 315   undefined loadURI(URI aURI, optional LoadURIOptions aOptions = {});
 316
 317   /**
 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`
 321    * directly.
 322    *
 323    * @param aURI
 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.
 330    */
 331   [Throws]
 332   undefined fixupAndLoadURIString(DOMString aURI, optional LoadURIOptions aOptions = {});
 333
 334    /**
 335     * Print the current document.
 336     *
 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.
 341     */
 342   [NewObject, BinaryName="printJS"]
 343   Promise<undefined> print(nsIPrintSettings aPrintSettings);
 344
 345   /**
 346    * These methods implement the nsIWebNavigation methods of the same names
 347    */
 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);
 353
 354   readonly attribute nsISHistory? sessionHistory;
 355   readonly attribute nsISHEntry? activeSessionHistoryEntry;
 356
 357   readonly attribute MediaController? mediaController;
 358
 359   undefined resetScalingZoom();
 360
 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;
 364
 365   undefined clearRestoreState();
 366
 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;
 370
 371   /**
 372    * This allows chrome to override the default choice of whether touch events
 373    * are available in a specific BrowsingContext and its descendents.
 374    */
 375   [SetterThrows] inherit attribute TouchEventsOverride touchEventsOverride;
 376
 377   /**
 378    * Set to true to configure the top-level BrowsingContext to default-target
 379    * user-initiated link clicks to _blank.
 380    */
 381   [SetterThrows] inherit attribute boolean targetTopLevelLinkClicksToBlank;
 382
 383   /**
 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
 387    * download.
 388    *
 389    * This value will be automatically set for documents created using
 390    * `window.open`.
 391    */
 392   [Throws]
 393   undefined setCrossGroupOpener(CanonicalBrowsingContext crossGroupOpener);
 394
 395   readonly attribute boolean isReplaced;
 396
 397
 398   /**
 399    * Notify APZ to start autoscrolling.
 400    *
 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
 404    *                            scroll.
 405    *
 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.
 410    */
 411   boolean startApzAutoscroll(float aAnchorX, float aAnchorY,
 412                              unsigned long long aScrollId,
 413                              unsigned long aPresShellId);
 414
 415   /**
 416    * Notify APZ to stop autoscrolling.
 417    */
 418   undefined stopApzAutoscroll(unsigned long long aScrollId,
 419                               unsigned long aPresShellId);
 420
 421   readonly attribute nsISHEntry? mostRecentLoadingSessionHistoryEntry;
 422
 423   /**
 424    * Indicates if the embedder element or an ancestor has hidden
 425    * visibility, or no frame.
 426    */
 427   readonly attribute boolean isUnderHiddenEmbedderElement;
 428 };
 429
 430 [Exposed=Window, ChromeOnly]
 431 interface BrowsingContextGroup {
 432   sequence<BrowsingContext> getToplevels();
 433
 434   readonly attribute unsigned long long id;
 435 };