gecko/dom/interfaces/base/nsIDOMWindow.idl

554 lines
19 KiB
Plaintext
Raw Normal View History

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 2000
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Vidur Apparao <vidur@netscape.com> (original author)
* Johnny Stenback <jst@netscape.com>
* Neil Deakin <enndeakin@sympatico.ca>
* Ms2ger <ms2ger@gmail.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "domstubs.idl"
interface nsIFrameRequestCallback;
interface nsIControllers;
interface nsIDOMBlob;
interface nsIDOMLocation;
interface nsIDOMMediaQueryList;
interface nsIDOMOfflineResourceList;
interface nsIDOMPerformance;
interface nsIDOMStorage;
interface nsIDOMStorageList;
interface nsIPrompt;
interface nsISelection;
interface nsIVariant;
[scriptable, uuid(8fc58f56-f769-4368-a098-edd08550cf1a)]
interface nsIDOMMozURLProperty : nsISupports
{
DOMString createObjectURL(in nsIDOMBlob blob);
void revokeObjectURL(in DOMString URL);
};
/**
* The nsIDOMWindow interface is the primary interface for a DOM
* window object. It represents a single window object that may
* contain child windows if the document in the window contains a
* HTML frameset document or if the document contains iframe elements.
*
* @see <http://www.whatwg.org/html/#window>
*/
[scriptable, uuid(17400E2B-F78B-4E69-B500-C2A3135A40FD)]
interface nsIDOMWindow : nsISupports
{
// the current browsing context
readonly attribute nsIDOMWindow window;
/* [replaceable] self */
readonly attribute nsIDOMWindow self;
/**
* Accessor for the document in this window.
*/
readonly attribute nsIDOMDocument document;
/**
* Set/Get the name of this window.
*
* This attribute is "replaceable" in JavaScript
*/
attribute DOMString name;
/* The setter that takes a string argument needs to be special cased! */
readonly attribute nsIDOMLocation location;
readonly attribute nsIDOMHistory history;
/* [replaceable] locationbar */
readonly attribute nsIDOMBarProp locationbar;
/* [replaceable] menubar */
readonly attribute nsIDOMBarProp menubar;
/* [replaceable] personalbar */
readonly attribute nsIDOMBarProp personalbar;
/**
* Accessor for the object that controls whether or not scrollbars
* are shown in this window.
*
* This attribute is "replaceable" in JavaScript
*/
readonly attribute nsIDOMBarProp scrollbars;
/* [replaceable] statusbar */
readonly attribute nsIDOMBarProp statusbar;
/* [replaceable] toolbar */
readonly attribute nsIDOMBarProp toolbar;
/* [replaceable] */
attribute DOMString status;
void close();
void stop();
void focus();
void blur();
// other browsing contexts
/* [replaceable] length */
readonly attribute unsigned long length;
/**
* |top| gets the root of the window hierarchy.
*
* This function does not cross chrome-content boundaries, so if this
* window's parent is of a different type, |top| will return this window.
*
* When script reads the top property, we run GetScriptableTop, which
* will not cross an <iframe mozbrowser> boundary.
*
* In contrast, C++ calls to GetTop are forwarded to GetRealTop, which
* ignores <iframe mozbrowser> boundaries.
*
* This property is "replaceable" in JavaScript.
*/
[binaryname(ScriptableTop)]
readonly attribute nsIDOMWindow top;
/**
* You shouldn't need to call this function directly; call GetTop instead.
*/
[noscript]
readonly attribute nsIDOMWindow realTop;
%{C++
nsresult GetTop(nsIDOMWindow **aWindow)
{
return GetRealTop(aWindow);
}
%}
/**
* |parent| gets this window's parent window. If this window has no parent,
* we return the window itself.
*
* This property does not cross chrome-content boundaries, so if this
* window's parent is of a different type, we return the window itself as its
* parent.
*
* When script reads the property (or when C++ calls ScriptableTop), this
* property does not cross <iframe mozbrowser> boundaries. In contrast, when
* C++ calls GetParent, we ignore the mozbrowser attribute.
*/
[binaryname(ScriptableParent)]
readonly attribute nsIDOMWindow parent;
/**
* You shouldn't need to read this property directly; call GetParent instead.
*/
[noscript]
readonly attribute nsIDOMWindow realParent;
%{C++
inline nsresult GetParent(nsIDOMWindow **aWindow)
{
return GetRealParent(aWindow);
}
%}
attribute nsIDOMWindow opener;
/**
* |frameElement| gets this window's <iframe> or <frame> element, if it has
* one.
*
* When script reads this property (or when C++ calls
* ScriptableFrameElement), we return |null| if the window is inside an
* <iframe mozbrowser>. In contrast, when C++ calls GetFrameElement, we
* ignore the mozbrowser attribute.
*/
[binaryname(ScriptableFrameElement)]
readonly attribute nsIDOMElement frameElement;
/**
* You shouldn't need to read this property directly; call GetFrameElement
* instead.
*/
[noscript]
readonly attribute nsIDOMElement realFrameElement;
%{C++
inline nsresult GetFrameElement(nsIDOMElement **aElement)
{
return GetRealFrameElement(aElement);
}
%}
// the user agent
readonly attribute nsIDOMNavigator navigator;
/**
* Get the application cache object for this window.
*/
readonly attribute nsIDOMOfflineResourceList applicationCache;
// user prompts
void alert(in DOMString text);
boolean confirm(in DOMString text);
// prompt() should return a null string if cancel is pressed
DOMString prompt([optional] in DOMString aMessage,
[optional] in DOMString aInitial);
void print();
nsIVariant showModalDialog(in DOMString aURI,
[optional] in nsIVariant aArgs,
[optional] in DOMString aOptions);
// cross-document messaging
/**
* Implements a safe message-passing system which can cross same-origin
* boundaries.
*
* This method, when called, causes a MessageEvent to be asynchronously
* dispatched at the primary document for the window upon which this method is
* called. (Note that the postMessage property on windows is allAccess and
* thus is readable cross-origin.) The dispatched event will have message as
* its data, the calling context's window as its source, and an origin
* determined by the calling context's main document URI. The targetOrigin
* argument specifies a URI and is used to restrict the message to be sent
* only when the target window has the same origin as targetOrigin (since,
* when the sender and the target have different origins, neither can read the
* location of the other).
*
* @see <http://www.whatwg.org/html/#dom-window-postmessage>
*/
[implicit_jscontext, binaryname(PostMessageMoz)]
void postMessage(in jsval message, in DOMString targetOrigin);
// WindowBase64
// Ascii base64 data to binary data and vice versa...
DOMString atob(in DOMString aAsciiString);
DOMString btoa(in DOMString aBase64Data);
// WindowSessionStorage
/**
* Session storage for the current browsing context.
*/
readonly attribute nsIDOMStorage sessionStorage;
// WindowLocalStorage
/**
* Local storage for the current browsing context.
*/
readonly attribute nsIDOMStorage localStorage;
// DOM Range
/**
* Method for accessing this window's selection object.
*/
nsISelection getSelection();
// CSSOM-View
// http://dev.w3.org/csswg/cssom-view/#extensions-to-the-window-interface
nsIDOMMediaQueryList matchMedia(in DOMString media_query_list);
readonly attribute nsIDOMScreen screen;
// viewport
attribute long innerWidth;
attribute long innerHeight;
// viewport scrolling
/**
* Accessor for the current x scroll position in this window in
* pixels.
*
* This attribute is "replaceable" in JavaScript
*/
readonly attribute long scrollX;
/* The offset in pixels by which the window is scrolled */
readonly attribute long pageXOffset;
/**
* Accessor for the current y scroll position in this window in
* pixels.
*
* This attribute is "replaceable" in JavaScript
*/
readonly attribute long scrollY;
/* The offset in pixels by which the window is scrolled */
readonly attribute long pageYOffset;
void scroll(in long xScroll, in long yScroll);
/**
* Method for scrolling this window to an absolute pixel offset.
*/
void scrollTo(in long xScroll, in long yScroll);
/**
* Method for scrolling this window to a pixel offset relative to
* the current scroll position.
*/
void scrollBy(in long xScrollDif, in long yScrollDif);
// client
attribute long screenX;
attribute long screenY;
attribute long outerWidth;
attribute long outerHeight;
// CSSOM
/**
* @see <http://dev.w3.org/csswg/cssom/#dom-window-getcomputedstyle>
*/
nsIDOMCSSStyleDeclaration getComputedStyle(in nsIDOMElement elt,
[optional] in DOMString pseudoElt);
// Mozilla extensions
/**
* Get the window root for this window. This is useful for hooking
* up event listeners to this window and every other window nested
* in the window root.
*/
[noscript] readonly attribute nsIDOMEventTarget windowRoot;
/**
* Accessor for the child windows in this window.
*/
[noscript] readonly attribute nsIDOMWindowCollection frames;
/**
* Set/Get the document scale factor as a multiplier on the default
* size. When setting this attribute, a NS_ERROR_NOT_IMPLEMENTED
* error may be returned by implementations not supporting
* zoom. Implementations not supporting zoom should return 1.0 all
* the time for the Get operation. 1.0 is equals normal size,
* i.e. no zoom.
*/
[noscript] attribute float textZoom;
/**
* Method for scrolling this window by a number of lines.
*/
void scrollByLines(in long numLines);
/**
* Method for scrolling this window by a number of pages.
*/
void scrollByPages(in long numPages);
/**
* Method for sizing this window to the content in the window.
*/
void sizeToContent();
/* [replaceable] content */
readonly attribute nsIDOMWindow content;
/* [replaceable] prompter */
[noscript] readonly attribute nsIPrompt prompter;
readonly attribute boolean closed;
// http://wiki.whatwg.org/wiki/Crypto
readonly attribute nsIDOMCrypto crypto;
readonly attribute nsIDOMPkcs11 pkcs11;
// XXX Shouldn't this be in nsIDOMChromeWindow?
/* [replaceable] controllers */
readonly attribute nsIControllers controllers;
attribute DOMString defaultStatus;
readonly attribute float mozInnerScreenX;
readonly attribute float mozInnerScreenY;
/* The maximum offset that the window can be scrolled to
(i.e., the document width/height minus the scrollport width/height) */
readonly attribute long scrollMaxX;
readonly attribute long scrollMaxY;
attribute boolean fullScreen;
void back();
void forward();
void home();
void moveTo(in long xPos, in long yPos);
void moveBy(in long xDif, in long yDif);
void resizeTo(in long width, in long height);
void resizeBy(in long widthDif, in long heightDif);
/**
* Open a new window with this one as the parent. This method will
* NOT examine the JS stack for purposes of determining a caller.
* This window will be used for security checks during the search by
* name and the default character set on the newly opened window
* will just be the default character set of this window.
*/
[noscript] nsIDOMWindow open(in DOMString url, in DOMString name,
in DOMString options);
/**
* This method works like open except that aExtraArgument gets
* converted into the array window.arguments in JS, if
* aExtraArgument is a nsISupportsArray then the individual items in
* the array are inserted into window.arguments, and primitive
* nsISupports (nsISupportsPrimitives) types are converted to native
* JS types when possible.
*/
[noscript] nsIDOMWindow openDialog(in DOMString url, in DOMString name,
in DOMString options,
in nsISupports aExtraArgument);
// XXX Should this be in nsIDOMChromeWindow?
void updateCommands(in DOMString action);
/* Find in page.
* @param str: the search pattern
* @param caseSensitive: is the search caseSensitive
* @param backwards: should we search backwards
* @param wrapAround: should we wrap the search
* @param wholeWord: should we search only for whole words
* @param searchInFrames: should we search through all frames
* @param showDialog: should we show the Find dialog
*/
boolean find([optional] in DOMString str,
[optional] in boolean caseSensitive,
[optional] in boolean backwards,
[optional] in boolean wrapAround,
[optional] in boolean wholeWord,
[optional] in boolean searchInFrames,
[optional] in boolean showDialog);
/**
* Returns the number of times this document for this window has
* been painted to the screen.
*/
readonly attribute unsigned long long mozPaintCount;
/**
* Request a refresh of this browser window.
*
* @see <http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/RequestAnimationFrame/Overview.html>
*/
// Argument is optional only so we can warn when it's null
long
mozRequestAnimationFrame([optional] in nsIFrameRequestCallback aCallback);
/**
* Cancel a refresh callback.
*/
void mozCancelAnimationFrame(in long aHandle);
// Backwards-compat shim for now to make Google maps work
void mozCancelRequestAnimationFrame(in long aHandle);
/**
* The current animation start time in milliseconds since the epoch.
*/
readonly attribute long long mozAnimationStartTime;
/**
* @see <http://dev.w3.org/2006/webapi/FileAPI/#creating-revoking>
*/
readonly attribute nsIDOMMozURLProperty URL;
/**
* HTML5 event attributes that only apply to windows and <body>/<frameset>
*/
[implicit_jscontext] attribute jsval onafterprint;
[implicit_jscontext] attribute jsval onbeforeprint;
[implicit_jscontext] attribute jsval onbeforeunload;
[implicit_jscontext] attribute jsval onhashchange;
[implicit_jscontext] attribute jsval onmessage;
[implicit_jscontext] attribute jsval onoffline;
[implicit_jscontext] attribute jsval ononline;
[implicit_jscontext] attribute jsval onpopstate;
[implicit_jscontext] attribute jsval onpagehide;
[implicit_jscontext] attribute jsval onpageshow;
// Not supported yet
// [implicit_jscontext] attribute jsval onredo;
[implicit_jscontext] attribute jsval onresize;
// Not supported yet
// [implicit_jscontext] attribute jsval onstorage;
// Not supported yet
// [implicit_jscontext] attribute jsval onundo;
[implicit_jscontext] attribute jsval onunload;
/**
* Non-HTML5 window-specific event attributes
*/
[implicit_jscontext] attribute jsval ondevicemotion;
[implicit_jscontext] attribute jsval ondeviceorientation;
[implicit_jscontext] attribute jsval onmouseenter;
[implicit_jscontext] attribute jsval onmouseleave;
};
[scriptable, uuid(2146c906-57f7-486c-a1b4-8cdb57ef577f)]
interface nsIDOMWindowPerformance : nsISupports
{
/**
* A namespace to hold performance related data and statistics.
*/
readonly attribute nsIDOMPerformance performance;
};
/**
* Empty interface for compatibility with older versions.
* @deprecated Use nsIDOMWindow instead
*/
[scriptable, uuid(8da641ab-906a-456e-97f2-b77df4ca2d95)]
interface nsIDOMWindowInternal : nsIDOMWindow {};