1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/interfaces/base/nsIDOMWindow.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,532 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "domstubs.idl"
1.10 +
1.11 +interface nsIFrameRequestCallback;
1.12 +interface nsIControllers;
1.13 +interface nsIDOMBlob;
1.14 +interface nsIDOMLocation;
1.15 +interface nsIDOMOfflineResourceList;
1.16 +interface nsIDOMStorage;
1.17 +interface nsIPrompt;
1.18 +interface nsISelection;
1.19 +interface nsIVariant;
1.20 +
1.21 +/**
1.22 + * The nsIDOMWindow interface is the primary interface for a DOM
1.23 + * window object. It represents a single window object that may
1.24 + * contain child windows if the document in the window contains a
1.25 + * HTML frameset document or if the document contains iframe elements.
1.26 + *
1.27 + * @see <http://www.whatwg.org/html/#window>
1.28 + */
1.29 +
1.30 +[scriptable, uuid(1b4a23a2-2ccf-4690-9da7-f3a7a8308381)]
1.31 +interface nsIDOMWindow : nsISupports
1.32 +{
1.33 + // the current browsing context
1.34 + readonly attribute nsIDOMWindow window;
1.35 +
1.36 + /* [replaceable] self */
1.37 + readonly attribute nsIDOMWindow self;
1.38 +
1.39 + /**
1.40 + * Accessor for the document in this window.
1.41 + */
1.42 + readonly attribute nsIDOMDocument document;
1.43 +
1.44 + /**
1.45 + * Set/Get the name of this window.
1.46 + *
1.47 + * This attribute is "replaceable" in JavaScript
1.48 + */
1.49 + attribute DOMString name;
1.50 +
1.51 + /* The setter that takes a string argument needs to be special cased! */
1.52 + readonly attribute nsIDOMLocation location;
1.53 +
1.54 + readonly attribute nsISupports history;
1.55 +
1.56 +
1.57 + /* [replaceable] locationbar */
1.58 + /* BarProp */
1.59 + readonly attribute nsISupports locationbar;
1.60 +
1.61 + /* [replaceable] menubar */
1.62 + /* BarProp */
1.63 + readonly attribute nsISupports menubar;
1.64 +
1.65 + /* [replaceable] personalbar */
1.66 + /* BarProp */
1.67 + readonly attribute nsISupports personalbar;
1.68 +
1.69 + /**
1.70 + * Accessor for the object that controls whether or not scrollbars
1.71 + * are shown in this window.
1.72 + *
1.73 + * This attribute is "replaceable" in JavaScript
1.74 + */
1.75 + /* BarProp */
1.76 + readonly attribute nsISupports scrollbars;
1.77 +
1.78 + /* [replaceable] statusbar */
1.79 + /* BarProp */
1.80 + readonly attribute nsISupports statusbar;
1.81 +
1.82 + /* [replaceable] toolbar */
1.83 + /* BarProp */
1.84 + readonly attribute nsISupports toolbar;
1.85 +
1.86 + /* [replaceable] */
1.87 + attribute DOMString status;
1.88 +
1.89 + void close();
1.90 + void stop();
1.91 + void focus();
1.92 + void blur();
1.93 +
1.94 +
1.95 + // other browsing contexts
1.96 + /* [replaceable] length */
1.97 + readonly attribute unsigned long length;
1.98 +
1.99 + /**
1.100 + * |top| gets the root of the window hierarchy.
1.101 + *
1.102 + * This function does not cross chrome-content boundaries, so if this
1.103 + * window's parent is of a different type, |top| will return this window.
1.104 + *
1.105 + * When script reads the top property, we run GetScriptableTop, which
1.106 + * will not cross an <iframe mozbrowser> boundary.
1.107 + *
1.108 + * In contrast, C++ calls to GetTop are forwarded to GetRealTop, which
1.109 + * ignores <iframe mozbrowser> boundaries.
1.110 + *
1.111 + * This property is "replaceable" in JavaScript.
1.112 + */
1.113 + [binaryname(ScriptableTop)]
1.114 + readonly attribute nsIDOMWindow top;
1.115 +
1.116 + /**
1.117 + * You shouldn't need to call this function directly; call GetTop instead.
1.118 + */
1.119 + [noscript]
1.120 + readonly attribute nsIDOMWindow realTop;
1.121 +
1.122 + %{C++
1.123 + nsresult GetTop(nsIDOMWindow **aWindow)
1.124 + {
1.125 + return GetRealTop(aWindow);
1.126 + }
1.127 + %}
1.128 +
1.129 + /**
1.130 + * |parent| gets this window's parent window. If this window has no parent,
1.131 + * we return the window itself.
1.132 + *
1.133 + * This property does not cross chrome-content boundaries, so if this
1.134 + * window's parent is of a different type, we return the window itself as its
1.135 + * parent.
1.136 + *
1.137 + * When script reads the property (or when C++ calls ScriptableTop), this
1.138 + * property does not cross <iframe mozbrowser> boundaries. In contrast, when
1.139 + * C++ calls GetParent, we ignore the mozbrowser attribute.
1.140 + */
1.141 + [binaryname(ScriptableParent)]
1.142 + readonly attribute nsIDOMWindow parent;
1.143 +
1.144 + /**
1.145 + * You shouldn't need to read this property directly; call GetParent instead.
1.146 + */
1.147 + [noscript]
1.148 + readonly attribute nsIDOMWindow realParent;
1.149 +
1.150 + %{C++
1.151 + inline nsresult GetParent(nsIDOMWindow **aWindow)
1.152 + {
1.153 + return GetRealParent(aWindow);
1.154 + }
1.155 + %}
1.156 +
1.157 + [implicit_jscontext, binaryname(ScriptableOpener)]
1.158 + attribute jsval opener;
1.159 +
1.160 + [noscript, binaryname(Opener)]
1.161 + attribute nsIDOMWindow openerWindow;
1.162 +
1.163 + /**
1.164 + * |frameElement| gets this window's <iframe> or <frame> element, if it has
1.165 + * one.
1.166 + *
1.167 + * When script reads this property (or when C++ calls
1.168 + * ScriptableFrameElement), we return |null| if the window is inside an
1.169 + * <iframe mozbrowser>. In contrast, when C++ calls GetFrameElement, we
1.170 + * ignore the mozbrowser attribute.
1.171 + */
1.172 + [binaryname(ScriptableFrameElement)]
1.173 + readonly attribute nsIDOMElement frameElement;
1.174 +
1.175 + /**
1.176 + * You shouldn't need to read this property directly; call GetFrameElement
1.177 + * instead.
1.178 + */
1.179 + [noscript]
1.180 + readonly attribute nsIDOMElement realFrameElement;
1.181 +
1.182 + %{C++
1.183 + inline nsresult GetFrameElement(nsIDOMElement **aElement)
1.184 + {
1.185 + return GetRealFrameElement(aElement);
1.186 + }
1.187 + %}
1.188 +
1.189 +
1.190 + // the user agent
1.191 + readonly attribute nsIDOMNavigator navigator;
1.192 +
1.193 + /**
1.194 + * Get the application cache object for this window.
1.195 + */
1.196 + readonly attribute nsIDOMOfflineResourceList applicationCache;
1.197 +
1.198 +
1.199 + // user prompts
1.200 + void alert([optional, Null(Stringify)] in DOMString text);
1.201 + boolean confirm([optional] in DOMString text);
1.202 +
1.203 + // prompt() should return a null string if cancel is pressed
1.204 + DOMString prompt([optional] in DOMString aMessage,
1.205 + [optional] in DOMString aInitial);
1.206 +
1.207 + void print();
1.208 +
1.209 + [optional_argc]
1.210 + nsIVariant showModalDialog(in DOMString aURI,
1.211 + [optional] in nsIVariant aArgs,
1.212 + [optional] in DOMString aOptions);
1.213 +
1.214 +
1.215 + // cross-document messaging
1.216 + /**
1.217 + * Implements a safe message-passing system which can cross same-origin
1.218 + * boundaries.
1.219 + *
1.220 + * This method, when called, causes a MessageEvent to be asynchronously
1.221 + * dispatched at the primary document for the window upon which this method is
1.222 + * called. (Note that the postMessage property on windows is allAccess and
1.223 + * thus is readable cross-origin.) The dispatched event will have message as
1.224 + * its data, the calling context's window as its source, and an origin
1.225 + * determined by the calling context's main document URI. The targetOrigin
1.226 + * argument specifies a URI and is used to restrict the message to be sent
1.227 + * only when the target window has the same origin as targetOrigin (since,
1.228 + * when the sender and the target have different origins, neither can read the
1.229 + * location of the other).
1.230 + *
1.231 + * @see <http://www.whatwg.org/html/#dom-window-postmessage>
1.232 + */
1.233 + [implicit_jscontext, binaryname(PostMessageMoz)]
1.234 + void postMessage(in jsval message, in DOMString targetOrigin,
1.235 + [optional] in jsval transfer);
1.236 +
1.237 +
1.238 + // WindowBase64
1.239 + // Ascii base64 data to binary data and vice versa...
1.240 + DOMString atob(in DOMString aAsciiString);
1.241 + DOMString btoa(in DOMString aBase64Data);
1.242 +
1.243 +
1.244 + // WindowSessionStorage
1.245 + /**
1.246 + * Session storage for the current browsing context.
1.247 + */
1.248 + readonly attribute nsIDOMStorage sessionStorage;
1.249 +
1.250 +
1.251 + // WindowLocalStorage
1.252 + /**
1.253 + * Local storage for the current browsing context.
1.254 + */
1.255 + readonly attribute nsIDOMStorage localStorage;
1.256 +
1.257 +
1.258 + // IndexedDB
1.259 + // https://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html#requests
1.260 + // IDBEnvironment
1.261 + readonly attribute nsISupports indexedDB;
1.262 + readonly attribute nsISupports mozIndexedDB;
1.263 +
1.264 +
1.265 + // DOM Range
1.266 + /**
1.267 + * Method for accessing this window's selection object.
1.268 + */
1.269 + nsISelection getSelection();
1.270 +
1.271 +
1.272 + // CSSOM-View
1.273 + // http://dev.w3.org/csswg/cssom-view/#extensions-to-the-window-interface
1.274 + nsISupports matchMedia(in DOMString media_query_list);
1.275 +
1.276 + readonly attribute nsIDOMScreen screen;
1.277 +
1.278 + // viewport
1.279 + attribute long innerWidth;
1.280 + attribute long innerHeight;
1.281 +
1.282 +
1.283 + // viewport scrolling
1.284 + /**
1.285 + * Accessor for the current x scroll position in this window in
1.286 + * pixels.
1.287 + *
1.288 + * This attribute is "replaceable" in JavaScript
1.289 + */
1.290 + readonly attribute long scrollX;
1.291 +
1.292 + /* The offset in pixels by which the window is scrolled */
1.293 + readonly attribute long pageXOffset;
1.294 +
1.295 + /**
1.296 + * Accessor for the current y scroll position in this window in
1.297 + * pixels.
1.298 + *
1.299 + * This attribute is "replaceable" in JavaScript
1.300 + */
1.301 + readonly attribute long scrollY;
1.302 +
1.303 + /* The offset in pixels by which the window is scrolled */
1.304 + readonly attribute long pageYOffset;
1.305 +
1.306 + void scroll(in long xScroll, in long yScroll);
1.307 +
1.308 + /**
1.309 + * Method for scrolling this window to an absolute pixel offset.
1.310 + */
1.311 + void scrollTo(in long xScroll, in long yScroll);
1.312 +
1.313 + /**
1.314 + * Method for scrolling this window to a pixel offset relative to
1.315 + * the current scroll position.
1.316 + */
1.317 + void scrollBy(in long xScrollDif, in long yScrollDif);
1.318 +
1.319 +
1.320 + // client
1.321 + attribute long screenX;
1.322 + attribute long screenY;
1.323 + attribute long outerWidth;
1.324 + attribute long outerHeight;
1.325 +
1.326 +
1.327 + // CSSOM
1.328 + /**
1.329 + * @see <http://dev.w3.org/csswg/cssom/#dom-window-getcomputedstyle>
1.330 + */
1.331 + nsIDOMCSSStyleDeclaration getComputedStyle(in nsIDOMElement elt,
1.332 + [optional] in DOMString pseudoElt);
1.333 + nsIDOMCSSStyleDeclaration getDefaultComputedStyle(in nsIDOMElement elt,
1.334 + [optional] in DOMString pseudoElt);
1.335 +
1.336 +
1.337 + // Mozilla extensions
1.338 + /**
1.339 + * Get the window root for this window. This is useful for hooking
1.340 + * up event listeners to this window and every other window nested
1.341 + * in the window root.
1.342 + */
1.343 + [noscript] readonly attribute nsIDOMEventTarget windowRoot;
1.344 +
1.345 + /**
1.346 + * Accessor for the child windows in this window.
1.347 + */
1.348 + [noscript] readonly attribute nsIDOMWindowCollection frames;
1.349 +
1.350 + /**
1.351 + * Set/Get the document scale factor as a multiplier on the default
1.352 + * size. When setting this attribute, a NS_ERROR_NOT_IMPLEMENTED
1.353 + * error may be returned by implementations not supporting
1.354 + * zoom. Implementations not supporting zoom should return 1.0 all
1.355 + * the time for the Get operation. 1.0 is equals normal size,
1.356 + * i.e. no zoom.
1.357 + */
1.358 + [noscript] attribute float textZoom;
1.359 +
1.360 + /**
1.361 + * Method for scrolling this window by a number of lines.
1.362 + */
1.363 + void scrollByLines(in long numLines);
1.364 +
1.365 + /**
1.366 + * Method for scrolling this window by a number of pages.
1.367 + */
1.368 + void scrollByPages(in long numPages);
1.369 +
1.370 + /**
1.371 + * Method for sizing this window to the content in the window.
1.372 + */
1.373 + void sizeToContent();
1.374 +
1.375 + /* [replaceable] content */
1.376 + [noscript] readonly attribute nsIDOMWindow content;
1.377 +
1.378 + /* [replaceable] prompter */
1.379 + [noscript] readonly attribute nsIPrompt prompter;
1.380 +
1.381 + readonly attribute boolean closed;
1.382 +
1.383 + readonly attribute nsIDOMCrypto crypto;
1.384 +
1.385 + // Note: this is [ChromeOnly] scriptable via WebIDL.
1.386 + [noscript] readonly attribute nsIControllers controllers;
1.387 +
1.388 + readonly attribute float mozInnerScreenX;
1.389 + readonly attribute float mozInnerScreenY;
1.390 + readonly attribute float devicePixelRatio;
1.391 +
1.392 + /* The maximum offset that the window can be scrolled to
1.393 + (i.e., the document width/height minus the scrollport width/height) */
1.394 + readonly attribute long scrollMaxX;
1.395 + readonly attribute long scrollMaxY;
1.396 +
1.397 + attribute boolean fullScreen;
1.398 +
1.399 + void back();
1.400 + void forward();
1.401 + void home();
1.402 +
1.403 + void moveTo(in long xPos, in long yPos);
1.404 + void moveBy(in long xDif, in long yDif);
1.405 + void resizeTo(in long width, in long height);
1.406 + void resizeBy(in long widthDif, in long heightDif);
1.407 +
1.408 + /**
1.409 + * Open a new window with this one as the parent. This method will
1.410 + * NOT examine the JS stack for purposes of determining a caller.
1.411 + * This window will be used for security checks during the search by
1.412 + * name and the default character set on the newly opened window
1.413 + * will just be the default character set of this window.
1.414 + */
1.415 + [noscript] nsIDOMWindow open(in DOMString url, in DOMString name,
1.416 + in DOMString options);
1.417 +
1.418 + /**
1.419 + * This method works like open except that aExtraArgument gets
1.420 + * converted into the array window.arguments in JS, if
1.421 + * aExtraArgument is a nsISupportsArray then the individual items in
1.422 + * the array are inserted into window.arguments, and primitive
1.423 + * nsISupports (nsISupportsPrimitives) types are converted to native
1.424 + * JS types when possible.
1.425 + */
1.426 + [noscript] nsIDOMWindow openDialog(in DOMString url, in DOMString name,
1.427 + in DOMString options,
1.428 + in nsISupports aExtraArgument);
1.429 +
1.430 + // XXX Should this be in nsIDOMChromeWindow?
1.431 + void updateCommands(in DOMString action);
1.432 +
1.433 + /* Find in page.
1.434 + * @param str: the search pattern
1.435 + * @param caseSensitive: is the search caseSensitive
1.436 + * @param backwards: should we search backwards
1.437 + * @param wrapAround: should we wrap the search
1.438 + * @param wholeWord: should we search only for whole words
1.439 + * @param searchInFrames: should we search through all frames
1.440 + * @param showDialog: should we show the Find dialog
1.441 + */
1.442 + boolean find([optional] in DOMString str,
1.443 + [optional] in boolean caseSensitive,
1.444 + [optional] in boolean backwards,
1.445 + [optional] in boolean wrapAround,
1.446 + [optional] in boolean wholeWord,
1.447 + [optional] in boolean searchInFrames,
1.448 + [optional] in boolean showDialog);
1.449 +
1.450 + /**
1.451 + * Returns the number of times this document for this window has
1.452 + * been painted to the screen.
1.453 + */
1.454 + readonly attribute unsigned long long mozPaintCount;
1.455 +
1.456 + /**
1.457 + * Request a refresh of this browser window.
1.458 + *
1.459 + * @see <http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/RequestAnimationFrame/Overview.html>
1.460 + */
1.461 + // Argument is optional only so we can warn when it's null
1.462 + long
1.463 + mozRequestAnimationFrame([optional] in nsIFrameRequestCallback aCallback);
1.464 + // jsval because we want a WebIDL callback here
1.465 + [implicit_jscontext]
1.466 + long requestAnimationFrame(in jsval aCallback);
1.467 +
1.468 + /**
1.469 + * Cancel a refresh callback.
1.470 + */
1.471 + void mozCancelAnimationFrame(in long aHandle);
1.472 + // Backwards-compat shim for now to make Google maps work
1.473 + void mozCancelRequestAnimationFrame(in long aHandle);
1.474 + void cancelAnimationFrame(in long aHandle);
1.475 +
1.476 + /**
1.477 + * The current animation start time in milliseconds since the epoch.
1.478 + */
1.479 + readonly attribute long long mozAnimationStartTime;
1.480 +
1.481 + /**
1.482 + * HTML5 event attributes that only apply to windows and <body>/<frameset>
1.483 + */
1.484 + [implicit_jscontext] attribute jsval onafterprint;
1.485 + [implicit_jscontext] attribute jsval onbeforeprint;
1.486 + [implicit_jscontext] attribute jsval onbeforeunload;
1.487 + [implicit_jscontext] attribute jsval onhashchange;
1.488 + [implicit_jscontext] attribute jsval onmessage;
1.489 + [implicit_jscontext] attribute jsval onoffline;
1.490 + [implicit_jscontext] attribute jsval ononline;
1.491 + [implicit_jscontext] attribute jsval onpopstate;
1.492 + [implicit_jscontext] attribute jsval onpagehide;
1.493 + [implicit_jscontext] attribute jsval onpageshow;
1.494 + // Not supported yet
1.495 + // [implicit_jscontext] attribute jsval onredo;
1.496 + [implicit_jscontext] attribute jsval onresize;
1.497 + // Not supported yet
1.498 + // [implicit_jscontext] attribute jsval onstorage;
1.499 + // Not supported yet
1.500 + // [implicit_jscontext] attribute jsval onundo;
1.501 + [implicit_jscontext] attribute jsval onunload;
1.502 +
1.503 + /**
1.504 + * Non-HTML5 window-specific event attributes
1.505 + */
1.506 + [implicit_jscontext] attribute jsval ondevicemotion;
1.507 + [implicit_jscontext] attribute jsval ondeviceorientation;
1.508 + [implicit_jscontext] attribute jsval ondeviceproximity;
1.509 + [implicit_jscontext] attribute jsval onuserproximity;
1.510 + [implicit_jscontext] attribute jsval ondevicelight;
1.511 +
1.512 + [implicit_jscontext] attribute jsval onmouseenter;
1.513 + [implicit_jscontext] attribute jsval onmouseleave;
1.514 +
1.515 + /**
1.516 + * Console API
1.517 + */
1.518 + [implicit_jscontext] attribute jsval console;
1.519 +};
1.520 +
1.521 +[scriptable, uuid(2146c906-57f7-486c-a1b4-8cdb57ef577f)]
1.522 +interface nsIDOMWindowPerformance : nsISupports
1.523 +{
1.524 + /**
1.525 + * A namespace to hold performance related data and statistics.
1.526 + */
1.527 + readonly attribute nsISupports performance;
1.528 +};
1.529 +
1.530 +/**
1.531 + * Empty interface for compatibility with older versions.
1.532 + * @deprecated Use nsIDOMWindow instead
1.533 + */
1.534 +[scriptable, uuid(2ec49e81-b2ba-4633-991a-f48f1e1d8800)]
1.535 +interface nsIDOMWindowInternal : nsIDOMWindow {};
