dom/webidl/Window.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 file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is:
   7  * http://www.whatwg.org/specs/web-apps/current-work/
   8  * https://dvcs.w3.org/hg/editing/raw-file/tip/editing.html
   9  * https://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html
  10  * http://dev.w3.org/csswg/cssom/
  11  * http://dev.w3.org/csswg/cssom-view/
  12  * https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/RequestAnimationFrame/Overview.html
  13  * https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/NavigationTiming/Overview.html
  14  * https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html
  15  * http://dvcs.w3.org/hg/speech-api/raw-file/tip/speechapi.html
  16  * https://w3c.github.io/webappsec-secure-contexts/#monkey-patching-global-object
  17  * https://w3c.github.io/requestidlecallback/
  18  * https://drafts.css-houdini.org/css-paint-api-1/#dom-window-paintworklet
  19  * https://wicg.github.io/visual-viewport/#the-visualviewport-interface
  20  */
  21
  22 interface Principal;
  23 interface nsIBrowserDOMWindow;
  24 interface XULControllers;
  25 interface nsIDOMWindowUtils;
  26 interface nsIPrintSettings;
  27
  28 // http://www.whatwg.org/specs/web-apps/current-work/
  29 [Global, LegacyUnenumerableNamedProperties, NeedResolve,
  30  Exposed=Window,
  31  InstrumentedProps=(AbsoluteOrientationSensor,
  32                     Accelerometer,
  33                     BackgroundFetchManager,
  34                     BackgroundFetchRecord,
  35                     BackgroundFetchRegistration,
  36                     BeforeInstallPromptEvent,
  37                     Bluetooth,
  38                     BluetoothCharacteristicProperties,
  39                     BluetoothDevice,
  40                     BluetoothRemoteGATTCharacteristic,
  41                     BluetoothRemoteGATTDescriptor,
  42                     BluetoothRemoteGATTServer,
  43                     BluetoothRemoteGATTService,
  44                     BluetoothUUID,
  45                     CanvasCaptureMediaStreamTrack,
  46                     chrome,
  47                     ClipboardItem,
  48                     CSSImageValue,
  49                     CSSKeywordValue,
  50                     CSSMathClamp,
  51                     CSSMathInvert,
  52                     CSSMathMax,
  53                     CSSMathMin,
  54                     CSSMathNegate,
  55                     CSSMathProduct,
  56                     CSSMathSum,
  57                     CSSMathValue,
  58                     CSSMatrixComponent,
  59                     CSSNumericArray,
  60                     CSSNumericValue,
  61                     CSSPerspective,
  62                     CSSPositionValue,
  63                     CSSPropertyRule,
  64                     CSSRotate,
  65                     CSSScale,
  66                     CSSSkew,
  67                     CSSSkewX,
  68                     CSSSkewY,
  69                     CSSStyleValue,
  70                     CSSTransformComponent,
  71                     CSSTransformValue,
  72                     CSSTranslate,
  73                     CSSUnitValue,
  74                     CSSUnparsedValue,
  75                     CSSVariableReferenceValue,
  76                     defaultStatus,
  77                     // Unfortunately, our telemetry histogram name generator
  78                     // (the one that generates TelemetryHistogramEnums.h) can't
  79                     // handle two DOM methods with names that only differ in
  80                     // case, because it forces everything to uppercase.
  81                     //defaultstatus,
  82                     DeviceMotionEventAcceleration,
  83                     DeviceMotionEventRotationRate,
  84                     DOMError,
  85                     EncodedVideoChunk,
  86                     EnterPictureInPictureEvent,
  87                     External,
  88                     FederatedCredential,
  89                     Gyroscope,
  90                     HTMLContentElement,
  91                     HTMLShadowElement,
  92                     ImageCapture,
  93                     InputDeviceCapabilities,
  94                     InputDeviceInfo,
  95                     Keyboard,
  96                     KeyboardLayoutMap,
  97                     LinearAccelerationSensor,
  98                     MediaSettingsRange,
  99                     MIDIAccess,
 100                     MIDIConnectionEvent,
 101                     MIDIInput,
 102                     MIDIInputMap,
 103                     MIDIMessageEvent,
 104                     MIDIOutput,
 105                     MIDIOutputMap,
 106                     MIDIPort,
 107                     NetworkInformation,
 108                     offscreenBuffering,
 109                     onbeforeinstallprompt,
 110                     oncancel,
 111                     onmousewheel,
 112                     onorientationchange,
 113                     onsearch,
 114                     onselectionchange,
 115                     openDatabase,
 116                     orientation,
 117                     OrientationSensor,
 118                     OverconstrainedError,
 119                     PasswordCredential,
 120                     PaymentAddress,
 121                     PaymentInstruments,
 122                     PaymentManager,
 123                     PaymentMethodChangeEvent,
 124                     PaymentRequest,
 125                     PaymentRequestUpdateEvent,
 126                     PaymentResponse,
 127                     PerformanceLongTaskTiming,
 128                     PhotoCapabilities,
 129                     PictureInPictureEvent,
 130                     PictureInPictureWindow,
 131                     Presentation,
 132                     PresentationAvailability,
 133                     PresentationConnection,
 134                     PresentationConnectionAvailableEvent,
 135                     PresentationConnectionCloseEvent,
 136                     PresentationConnectionList,
 137                     PresentationReceiver,
 138                     PresentationRequest,
 139                     RelativeOrientationSensor,
 140                     RemotePlayback,
 141                     Report,
 142                     ReportBody,
 143                     ReportingObserver,
 144                     RTCError,
 145                     RTCErrorEvent,
 146                     RTCIceTransport,
 147                     RTCPeerConnectionIceErrorEvent,
 148                     Sensor,
 149                     SensorErrorEvent,
 150                     SpeechRecognitionAlternative,
 151                     SpeechRecognitionResult,
 152                     SpeechRecognitionResultList,
 153                     styleMedia,
 154                     StylePropertyMap,
 155                     StylePropertyMapReadOnly,
 156                     SVGDiscardElement,
 157                     SyncManager,
 158                     TaskAttributionTiming,
 159                     TextEvent,
 160                     Touch,
 161                     TouchEvent,
 162                     TouchList,
 163                     USB,
 164                     USBAlternateInterface,
 165                     USBConfiguration,
 166                     USBConnectionEvent,
 167                     USBDevice,
 168                     USBEndpoint,
 169                     USBInterface,
 170                     USBInTransferResult,
 171                     USBIsochronousInTransferPacket,
 172                     USBIsochronousInTransferResult,
 173                     USBIsochronousOutTransferPacket,
 174                     USBIsochronousOutTransferResult,
 175                     USBOutTransferResult,
 176                     UserActivation,
 177                     VideoColorSpace,
 178                     VideoDecoder,
 179                     VideoEncoder,
 180                     VideoFrame,
 181                     WakeLock,
 182                     WakeLockSentinel,
 183                     webkitCancelAnimationFrame,
 184                     webkitMediaStream,
 185                     WebKitMutationObserver,
 186                     webkitRequestAnimationFrame,
 187                     webkitRequestFileSystem,
 188                     webkitResolveLocalFileSystemURL,
 189                     webkitRTCPeerConnection,
 190                     webkitSpeechGrammar,
 191                     webkitSpeechGrammarList,
 192                     webkitSpeechRecognition,
 193                     webkitSpeechRecognitionError,
 194                     webkitSpeechRecognitionEvent,
 195                     webkitStorageInfo)]
 196 /*sealed*/ interface Window : EventTarget {
 197   // the current browsing context
 198   [LegacyUnforgeable, Constant, StoreInSlot,
 199    CrossOriginReadable] readonly attribute WindowProxy window;
 200   [Replaceable, Constant, StoreInSlot,
 201    CrossOriginReadable] readonly attribute WindowProxy self;
 202   [LegacyUnforgeable, StoreInSlot, Pure] readonly attribute Document? document;
 203   [Throws] attribute DOMString name;
 204   [PutForwards=href, LegacyUnforgeable, CrossOriginReadable,
 205    CrossOriginWritable] readonly attribute Location location;
 206   [Throws] readonly attribute History history;
 207   readonly attribute CustomElementRegistry customElements;
 208   [Replaceable, Throws] readonly attribute BarProp locationbar;
 209   [Replaceable, Throws] readonly attribute BarProp menubar;
 210   [Replaceable, Throws] readonly attribute BarProp personalbar;
 211   [Replaceable, Throws] readonly attribute BarProp scrollbars;
 212   [Replaceable, Throws] readonly attribute BarProp statusbar;
 213   [Replaceable, Throws] readonly attribute BarProp toolbar;
 214   [Throws] attribute DOMString status;
 215   [Throws, CrossOriginCallable, NeedsCallerType] undefined close();
 216   [Throws, CrossOriginReadable] readonly attribute boolean closed;
 217   [Throws] undefined stop();
 218   [Throws, CrossOriginCallable, NeedsCallerType] undefined focus();
 219   [Throws, CrossOriginCallable, NeedsCallerType] undefined blur();
 220   [Replaceable, Pref="dom.window.event.enabled"] readonly attribute (Event or undefined) event;
 221
 222   // other browsing contexts
 223   [Replaceable, Throws, CrossOriginReadable] readonly attribute WindowProxy frames;
 224   [Replaceable, CrossOriginReadable] readonly attribute unsigned long length;
 225   //[Unforgeable, Throws, CrossOriginReadable] readonly attribute WindowProxy top;
 226   [LegacyUnforgeable, Throws, CrossOriginReadable] readonly attribute WindowProxy? top;
 227   [Throws, CrossOriginReadable] attribute any opener;
 228   //[Throws] readonly attribute WindowProxy parent;
 229   [Replaceable, Throws, CrossOriginReadable] readonly attribute WindowProxy? parent;
 230   [Throws, NeedsSubjectPrincipal] readonly attribute Element? frameElement;
 231   //[Throws] WindowProxy? open(optional USVString url = "about:blank", optional DOMString target = "_blank", [TreatNullAs=EmptyString] optional DOMString features = "");
 232   [Throws] WindowProxy? open(optional USVString url = "", optional DOMString target = "", optional [LegacyNullToEmptyString] DOMString features = "");
 233   getter object (DOMString name);
 234
 235   // the user agent
 236   readonly attribute Navigator navigator;
 237   [Pref="dom.window.clientinformation.enabled", BinaryName="Navigator"]
 238   readonly attribute Navigator clientInformation;
 239
 240   [Replaceable] readonly attribute External external;
 241
 242   // user prompts
 243   [Throws, NeedsSubjectPrincipal] undefined alert();
 244   [Throws, NeedsSubjectPrincipal] undefined alert(DOMString message);
 245   [Throws, NeedsSubjectPrincipal] boolean confirm(optional DOMString message = "");
 246   [Throws, NeedsSubjectPrincipal] DOMString? prompt(optional DOMString message = "", optional DOMString default = "");
 247   [Throws]
 248   undefined print();
 249
 250   // Returns a window that you can use for a print preview.
 251   //
 252   // This may reuse an existing window if this window is already a print
 253   // preview document, or if you pass a docshell explicitly.
 254   [Throws, Func="nsContentUtils::IsCallerChromeOrFuzzingEnabled"]
 255   WindowProxy? printPreview(optional nsIPrintSettings? settings = null,
 256                             optional nsIWebProgressListener? listener = null,
 257                             optional nsIDocShell? docShellToPreviewInto = null);
 258
 259   [Throws, CrossOriginCallable, NeedsSubjectPrincipal,
 260    BinaryName="postMessageMoz"]
 261   undefined postMessage(any message, DOMString targetOrigin, optional sequence<object> transfer = []);
 262   [Throws, CrossOriginCallable, NeedsSubjectPrincipal,
 263    BinaryName="postMessageMoz"]
 264   undefined postMessage(any message, optional WindowPostMessageOptions options = {});
 265
 266   // also has obsolete members
 267 };
 268 Window includes GlobalEventHandlers;
 269 Window includes WindowEventHandlers;
 270
 271 // http://www.whatwg.org/specs/web-apps/current-work/
 272 interface mixin WindowSessionStorage {
 273   //[Throws] readonly attribute Storage sessionStorage;
 274   [Throws] readonly attribute Storage? sessionStorage;
 275 };
 276 Window includes WindowSessionStorage;
 277
 278 // http://www.whatwg.org/specs/web-apps/current-work/
 279 interface mixin WindowLocalStorage {
 280   [Throws] readonly attribute Storage? localStorage;
 281 };
 282 Window includes WindowLocalStorage;
 283
 284 // http://www.whatwg.org/specs/web-apps/current-work/
 285 partial interface Window {
 286   undefined captureEvents();
 287   undefined releaseEvents();
 288 };
 289
 290 // https://dvcs.w3.org/hg/editing/raw-file/tip/editing.html
 291 partial interface Window {
 292   //[Throws] Selection getSelection();
 293   [Throws] Selection? getSelection();
 294 };
 295
 296 // https://drafts.csswg.org/cssom/#extensions-to-the-window-interface
 297 partial interface Window {
 298   //[NewObject, Throws] CSSStyleDeclaration getComputedStyle(Element elt, optional DOMString? pseudoElt = "");
 299   [NewObject, Throws] CSSStyleDeclaration? getComputedStyle(Element elt, optional DOMString? pseudoElt = "");
 300 };
 301
 302 // http://dev.w3.org/csswg/cssom-view/
 303 enum ScrollBehavior { "auto", "instant", "smooth" };
 304
 305 dictionary ScrollOptions {
 306   ScrollBehavior behavior = "auto";
 307 };
 308
 309 dictionary ScrollToOptions : ScrollOptions {
 310   unrestricted double left;
 311   unrestricted double top;
 312 };
 313
 314 partial interface Window {
 315   //[Throws, NewObject, NeedsCallerType] MediaQueryList matchMedia(DOMString query);
 316   [Throws, NewObject, NeedsCallerType] MediaQueryList? matchMedia(UTF8String query);
 317
 318   [SameObject, Replaceable] readonly attribute Screen screen;
 319
 320   // browsing context
 321   //[Throws] undefined moveTo(double x, double y);
 322   //[Throws] undefined moveBy(double x, double y);
 323   //[Throws] undefined resizeTo(double x, double y);
 324   //[Throws] undefined resizeBy(double x, double y);
 325   [Throws, NeedsCallerType] undefined moveTo(long x, long y);
 326   [Throws, NeedsCallerType] undefined moveBy(long x, long y);
 327   [Throws, NeedsCallerType] undefined resizeTo(long x, long y);
 328   [Throws, NeedsCallerType] undefined resizeBy(long x, long y);
 329
 330   // viewport
 331   [Replaceable, Throws] readonly attribute double innerWidth;
 332   [Replaceable, Throws] readonly attribute double innerHeight;
 333
 334   // viewport scrolling
 335   undefined scroll(unrestricted double x, unrestricted double y);
 336   undefined scroll(optional ScrollToOptions options = {});
 337   undefined scrollTo(unrestricted double x, unrestricted double y);
 338   undefined scrollTo(optional ScrollToOptions options = {});
 339   undefined scrollBy(unrestricted double x, unrestricted double y);
 340   undefined scrollBy(optional ScrollToOptions options = {});
 341   // mozScrollSnap is used by chrome to perform scroll snapping after the
 342   // user performs actions that may affect scroll position
 343   // mozScrollSnap is deprecated, to be replaced by a web accessible API, such
 344   // as an extension to the ScrollOptions dictionary.  See bug 1137937.
 345   [ChromeOnly] undefined mozScrollSnap();
 346   // The four properties below are double per spec at the moment, but whether
 347   // that will continue is unclear.
 348   [Replaceable, Throws] readonly attribute double scrollX;
 349   [Replaceable, Throws] readonly attribute double pageXOffset;
 350   [Replaceable, Throws] readonly attribute double scrollY;
 351   [Replaceable, Throws] readonly attribute double pageYOffset;
 352
 353   // Aliases for screenX / screenY.
 354   [Replaceable, Throws, NeedsCallerType] readonly attribute double screenLeft;
 355   [Replaceable, Throws, NeedsCallerType] readonly attribute double screenTop;
 356
 357   // client
 358   [Replaceable, Throws, NeedsCallerType] readonly attribute double screenX;
 359   [Replaceable, Throws, NeedsCallerType] readonly attribute double screenY;
 360   [Replaceable, Throws, NeedsCallerType] readonly attribute double outerWidth;
 361   [Replaceable, Throws, NeedsCallerType] readonly attribute double outerHeight;
 362 };
 363
 364 // https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#animation-frames
 365 Window includes AnimationFrameProvider;
 366
 367 // https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/NavigationTiming/Overview.html
 368 partial interface Window {
 369   [Replaceable, Pure, StoreInSlot] readonly attribute Performance? performance;
 370 };
 371
 372 // https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html
 373 Window includes GlobalCrypto;
 374
 375 dictionary SizeToContentConstraints {
 376   long maxWidth = 0;
 377   long maxHeight = 0;
 378   long prefWidth = 0;
 379 };
 380
 381 #ifdef MOZ_WEBSPEECH
 382 // http://dvcs.w3.org/hg/speech-api/raw-file/tip/speechapi.html
 383 interface mixin SpeechSynthesisGetter {
 384   [Throws, Pref="media.webspeech.synth.enabled"] readonly attribute SpeechSynthesis speechSynthesis;
 385 };
 386
 387 Window includes SpeechSynthesisGetter;
 388 #endif
 389
 390 // Mozilla-specific stuff
 391 partial interface Window {
 392   //[NewObject, Throws] CSSStyleDeclaration getDefaultComputedStyle(Element elt, optional DOMString pseudoElt = "");
 393   [NewObject, Throws] CSSStyleDeclaration? getDefaultComputedStyle(Element elt, optional DOMString pseudoElt = "");
 394
 395   // Mozilla extensions
 396   /**
 397    * Method for scrolling this window by a number of lines.
 398    */
 399   undefined                 scrollByLines(long numLines, optional ScrollOptions options = {});
 400
 401   /**
 402    * Method for scrolling this window by a number of pages.
 403    */
 404   undefined                 scrollByPages(long numPages, optional ScrollOptions options = {});
 405
 406   // Gecko specific API that allows a web page to resize the browser window.
 407   // Dropping support in bug 1600400.
 408   [Throws, NeedsCallerType,
 409    Deprecated="SizeToContent",
 410    Func="nsGlobalWindowInner::IsSizeToContentEnabled"]
 411   undefined sizeToContent();
 412
 413   /**
 414    * Chrome-only method for sizing to content with a maximum-size constraint on
 415    * either (or both) directions.
 416    */
 417   [Throws, ChromeOnly] undefined sizeToContentConstrained(optional SizeToContentConstraints constraints = {});
 418
 419   [ChromeOnly, Replaceable, Throws] readonly attribute XULControllers controllers;
 420
 421   [ChromeOnly, Throws] readonly attribute Element? realFrameElement;
 422
 423   [ChromeOnly] readonly attribute nsIDocShell? docShell;
 424
 425   [ChromeOnly, Constant, CrossOriginReadable, BinaryName="getBrowsingContext"]
 426   readonly attribute BrowsingContext browsingContext;
 427
 428   [Throws, NeedsCallerType]
 429   readonly attribute float mozInnerScreenX;
 430   [Throws, NeedsCallerType]
 431   readonly attribute float mozInnerScreenY;
 432   [Replaceable, Throws, NeedsCallerType]
 433   readonly attribute double devicePixelRatio;
 434
 435   // Allows chrome code to convert desktop pixels to device pixels and vice
 436   // versa. Useful for interacting with the screen manager.
 437   [ChromeOnly, Throws]
 438   readonly attribute double desktopToDeviceScale;
 439
 440   // Returns the amount of CSS pixels relative to this window we're allowed to
 441   // go out of the screen. This is needed so that SessionRestore is able to
 442   // position windows that use client-side decorations correctly, but still
 443   // pull mispositioned windows into the screen.
 444   [ChromeOnly]
 445   readonly attribute double screenEdgeSlopX;
 446   [ChromeOnly]
 447   readonly attribute double screenEdgeSlopY;
 448
 449
 450   /* The maximum offset that the window can be scrolled to
 451      (i.e., the document width/height minus the scrollport width/height) */
 452   [ChromeOnly, Throws]  readonly attribute long   scrollMinX;
 453   [ChromeOnly, Throws]  readonly attribute long   scrollMinY;
 454   [Replaceable, Throws] readonly attribute long   scrollMaxX;
 455   [Replaceable, Throws] readonly attribute long   scrollMaxY;
 456
 457   [Throws] attribute boolean fullScreen;
 458
 459   undefined                 updateCommands(DOMString action);
 460
 461   /* Find in page.
 462    * @param str: the search pattern
 463    * @param caseSensitive: is the search caseSensitive
 464    * @param backwards: should we search backwards
 465    * @param wrapAround: should we wrap the search
 466    * @param wholeWord: should we search only for whole words
 467    * @param searchInFrames: should we search through all frames
 468    * @param showDialog: should we show the Find dialog
 469    */
 470   [Throws] boolean    find(optional DOMString str = "",
 471                            optional boolean caseSensitive = false,
 472                            optional boolean backwards = false,
 473                            optional boolean wrapAround = false,
 474                            optional boolean wholeWord = false,
 475                            optional boolean searchInFrames = false,
 476                            optional boolean showDialog = false);
 477
 478            attribute EventHandler ondevicemotion;
 479            attribute EventHandler ondeviceorientation;
 480            attribute EventHandler ondeviceorientationabsolute;
 481            [Pref="device.sensors.proximity.enabled"]
 482            attribute EventHandler onuserproximity;
 483            [Pref="device.sensors.ambientLight.enabled"]
 484            attribute EventHandler ondevicelight;
 485
 486   undefined                 dump(DOMString str);
 487
 488   /**
 489    * This method is here for backwards compatibility with 4.x only,
 490    * its implementation is a no-op
 491    */
 492   undefined                 setResizable(boolean resizable);
 493
 494   /**
 495    * This is the scriptable version of
 496    * nsPIDOMWindow::OpenDialog() that takes 3 optional
 497    * arguments, plus any additional arguments are passed on as
 498    * arguments on the dialog's window object (window.arguments).
 499    */
 500   [Throws, ChromeOnly] WindowProxy? openDialog(optional DOMString url = "",
 501                                                optional DOMString name = "",
 502                                                optional DOMString options = "",
 503                                                any... extraArguments);
 504
 505   [ChromeOnly,
 506    NonEnumerable, Replaceable, Throws, NeedsCallerType]
 507   readonly attribute object? content;
 508
 509   [Throws, ChromeOnly] any getInterface(any iid);
 510
 511   /**
 512    * Same as nsIDOMWindow.windowRoot, useful for event listener targeting.
 513    */
 514   [ChromeOnly, Throws]
 515   readonly attribute WindowRoot? windowRoot;
 516
 517   /**
 518    * ChromeOnly method to determine if a particular window should see console
 519    * reports from service workers of the given scope.
 520    */
 521   [ChromeOnly]
 522   boolean shouldReportForServiceWorkerScope(USVString aScope);
 523
 524   /**
 525    * InstallTrigger is used for extension installs.  Ideally it would
 526    * be something like a WebIDL namespace, but we don't support
 527    * JS-implemented static things yet.  See bug 863952.
 528    */
 529   [Replaceable, Deprecated="InstallTriggerDeprecated", Pref="extensions.InstallTrigger.enabled"]
 530   readonly attribute InstallTriggerImpl? InstallTrigger;
 531
 532   /**
 533    * Get the nsIDOMWindowUtils for this window.
 534    */
 535   [Constant, Throws, ChromeOnly]
 536   readonly attribute nsIDOMWindowUtils windowUtils;
 537
 538   [Pure, ChromeOnly]
 539   readonly attribute WindowGlobalChild? windowGlobalChild;
 540
 541   /**
 542    * The principal of the client source of the window. This is supposed to be
 543    * used for the service worker.
 544    *
 545    * This is used for APIs like https://w3c.github.io/push-api/ that extend
 546    * ServiceWorkerRegistration and therefore need to operate consistently with
 547    * ServiceWorkers and its Clients API. The client principal is the appropriate
 548    * principal to pass to all nsIServiceWorkerManager APIs.
 549    *
 550    * Note that the client principal will be different from the node principal of
 551    * the window's document if the window is in a third-party context when dFPI
 552    * is enabled. In this case, the client principal will be the partitioned
 553    * principal to support the service worker partitioning.
 554    */
 555   [ChromeOnly]
 556   readonly attribute Principal? clientPrincipal;
 557
 558   /**
 559    *  Whether the chrome window is currently in a full screen transition. This
 560    *  flag is updated from FullscreenTransitionTask.
 561    *  Always set to false for non-chrome windows.
 562    */
 563   [ChromeOnly]
 564   readonly attribute boolean isInFullScreenTransition;
 565 };
 566
 567 Window includes TouchEventHandlers;
 568
 569 Window includes OnErrorEventHandlerForWindow;
 570
 571 #if defined(MOZ_WIDGET_ANDROID)
 572 // https://compat.spec.whatwg.org/#windoworientation-interface
 573 partial interface Window {
 574   [NeedsCallerType]
 575   readonly attribute short orientation;
 576            attribute EventHandler onorientationchange;
 577 };
 578 #endif
 579
 580 [MOZ_CAN_RUN_SCRIPT_BOUNDARY]
 581 callback PromiseDocumentFlushedCallback = any ();
 582
 583 // Mozilla extensions for Chrome windows.
 584 partial interface Window {
 585   // The STATE_* constants need to match the corresponding enum in nsGlobalWindow.cpp.
 586   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 587   const unsigned short STATE_MAXIMIZED = 1;
 588   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 589   const unsigned short STATE_MINIMIZED = 2;
 590   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 591   const unsigned short STATE_NORMAL = 3;
 592   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 593   const unsigned short STATE_FULLSCREEN = 4;
 594
 595   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 596   readonly attribute unsigned short windowState;
 597
 598   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 599   readonly attribute boolean isFullyOccluded;
 600
 601   /**
 602    * browserDOMWindow provides access to yet another layer of
 603    * utility functions implemented by chrome script. It will be null
 604    * for DOMWindows not corresponding to browsers.
 605    */
 606   [Throws, Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 607            attribute nsIBrowserDOMWindow? browserDOMWindow;
 608
 609   [Throws, Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 610   undefined                 getAttention();
 611
 612   [Throws, Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 613   undefined                 getAttentionWithCycleCount(long aCycleCount);
 614
 615   [Throws, Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 616   undefined                 setCursor(UTF8String cursor);
 617
 618   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 619   undefined                 maximize();
 620   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 621   undefined                 minimize();
 622   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 623   undefined                 restore();
 624   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 625   DOMString                 getWorkspaceID();
 626   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 627   undefined                 moveToWorkspace(DOMString workspaceID);
 628
 629   /**
 630    * Notify a default button is loaded on a dialog or a wizard.
 631    * defaultButton is the default button.
 632    */
 633   [Throws, Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 634   undefined notifyDefaultButtonLoaded(Element defaultButton);
 635
 636   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 637   readonly attribute ChromeMessageBroadcaster messageManager;
 638
 639   /**
 640    * Returns the message manager identified by the given group name that
 641    * manages all frame loaders belonging to that group.
 642    */
 643   [Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 644   ChromeMessageBroadcaster getGroupMessageManager(DOMString aGroup);
 645
 646   /**
 647    * Calls the given function as soon as a style or layout flush for the
 648    * top-level document is not necessary, and returns a Promise which
 649    * resolves to the callback's return value after it executes.
 650    *
 651    * In the event that the window goes away before a flush can occur, the
 652    * callback will still be called and the Promise resolved as the window
 653    * tears itself down.
 654    *
 655    * The callback _must not modify the DOM for any window in any way_. If it
 656    * does, after finishing executing, the Promise returned by
 657    * promiseDocumentFlushed will reject with
 658    * NS_ERROR_DOM_NO_MODIFICATION_ALLOWED_ERR.
 659    *
 660    * Note that the callback can be called either synchronously or asynchronously
 661    * depending on whether or not flushes are pending:
 662    *
 663    *   The callback will be called synchronously when calling
 664    *   promiseDocumentFlushed when NO flushes are already pending. This is
 665    *   to ensure that no script has a chance to dirty the DOM before the callback
 666    *   is called.
 667    *
 668    *   The callback will be called asynchronously if a flush is pending.
 669    *
 670    * The expected execution order is that all pending callbacks will
 671    * be fired first (and in the order that they were queued) and then the
 672    * Promise resolution handlers will all be invoked later on during the
 673    * next microtask checkpoint.
 674    *
 675    * Using window.top.promiseDocumentFlushed in combination with a callback
 676    * that is querying items in a window that might be swapped out via
 677    * nsFrameLoader::SwapWithOtherLoader is highly discouraged. For example:
 678    *
 679    *   let result = await window.top.promiseDocumentFlushed(() => {
 680    *     return window.document.body.getBoundingClientRect();
 681    *   });
 682    *
 683    *   If "window" might get swapped out via nsFrameLoader::SwapWithOtherLoader
 684    *   at any time, then the callback might get called when the new host window
 685    *   will still incur layout flushes, since it's only the original host window
 686    *   that's being monitored via window.top.promiseDocumentFlushed.
 687    *
 688    *   See bug 1519407 for further details.
 689    *
 690    * promiseDocumentFlushed does not support re-entrancy - so calling it from
 691    * within a promiseDocumentFlushed callback will result in the inner call
 692    * throwing an NS_ERROR_FAILURE exception, and the outer Promise rejecting
 693    * with that exception.
 694    *
 695    * The callback function *must not make any changes which would require
 696    * a style or layout flush*.
 697    *
 698    * Also throws NS_ERROR_FAILURE if the window is not in a state where flushes
 699    * can be waited for (for example, the PresShell has not yet been created).
 700    *
 701    * @param {function} callback
 702    * @returns {Promise}
 703    */
 704   [NewObject, Func="nsGlobalWindowInner::IsPrivilegedChromeWindow"]
 705   Promise<any> promiseDocumentFlushed(PromiseDocumentFlushedCallback callback);
 706
 707   [Func="IsChromeOrUAWidget"]
 708   readonly attribute boolean isChromeWindow;
 709
 710   [Func="nsGlobalWindowInner::IsGleanNeeded"]
 711   readonly attribute GleanImpl Glean;
 712   [Func="nsGlobalWindowInner::IsGleanNeeded"]
 713   readonly attribute GleanPingsImpl GleanPings;
 714 };
 715
 716 partial interface Window {
 717   [Pref="dom.vr.enabled"]
 718   attribute EventHandler onvrdisplayconnect;
 719   [Pref="dom.vr.enabled"]
 720   attribute EventHandler onvrdisplaydisconnect;
 721   [Pref="dom.vr.enabled"]
 722   attribute EventHandler onvrdisplayactivate;
 723   [Pref="dom.vr.enabled"]
 724   attribute EventHandler onvrdisplaydeactivate;
 725   [Pref="dom.vr.enabled"]
 726   attribute EventHandler onvrdisplaypresentchange;
 727 };
 728
 729 #ifndef RELEASE_OR_BETA
 730 // https://drafts.css-houdini.org/css-paint-api-1/#dom-window-paintworklet
 731 partial interface Window {
 732     [Pref="dom.paintWorklet.enabled", Throws]
 733     readonly attribute Worklet paintWorklet;
 734 };
 735 #endif
 736
 737 Window includes WindowOrWorkerGlobalScope;
 738
 739 partial interface Window {
 740   [Throws]
 741   unsigned long requestIdleCallback(IdleRequestCallback callback,
 742                                     optional IdleRequestOptions options = {});
 743   undefined     cancelIdleCallback(unsigned long handle);
 744 };
 745
 746 dictionary IdleRequestOptions {
 747   unsigned long timeout;
 748 };
 749
 750 callback IdleRequestCallback = undefined (IdleDeadline deadline);
 751
 752 partial interface Window {
 753   /**
 754    * Returns a list of locales that the internationalization components
 755    * should be localized to.
 756    *
 757    * The function name refers to Regional Preferences which can be either
 758    * fetched from the internal internationalization database (CLDR), or
 759    * from the host environment.
 760    *
 761    * The result is a sorted list of valid locale IDs and it should be
 762    * used for all APIs that accept list of locales, like ECMA402 and L10n APIs.
 763    *
 764    * This API always returns at least one locale.
 765    *
 766    * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"]
 767    */
 768   [Func="IsChromeOrUAWidget"]
 769   sequence<DOMString> getRegionalPrefsLocales();
 770
 771   /**
 772    * Returns a list of locales that the web content would know from the user.
 773    *
 774    * One of the fingerprinting technique is to recognize users from their locales
 775    * exposed to web content. For those components that would be fingerprintable
 776    * from the locale should call this API instead of |getRegionalPrefsLocales()|.
 777    *
 778    * If the pref is set to spoof locale setting, this function will return the
 779    * spoofed locale, otherwise it returns what |getRegionalPrefsLocales()| returns.
 780    *
 781    * This API always returns at least one locale.
 782    *
 783    * Example: ["en-US"]
 784    */
 785   [Func="IsChromeOrUAWidget"]
 786   sequence<DOMString> getWebExposedLocales();
 787
 788   /**
 789    * Getter funcion for IntlUtils, which provides helper functions for
 790    * localization.
 791    */
 792   [Throws, Func="IsChromeOrUAWidget"]
 793   readonly attribute IntlUtils intlUtils;
 794 };
 795
 796 partial interface Window {
 797   [SameObject, Replaceable]
 798   readonly attribute VisualViewport visualViewport;
 799 };
 800
 801 // Used to assign marks to appear on the scrollbar when
 802 // finding on a page.
 803 partial interface Window {
 804   // The marks are values between 0 and scrollMax{X,Y} - scrollMin{X,Y}.
 805   [ChromeOnly]
 806   undefined setScrollMarks(sequence<unsigned long> marks,
 807                            optional boolean onHorizontalScrollbar = false);
 808 };
 809
 810 dictionary WindowPostMessageOptions : StructuredSerializeOptions {
 811   USVString targetOrigin = "/";
 812 };