thunderbird-dev 1:24.4.0+build1-0ubuntu1 / usr / share / idl / thunderbird / nsIDOMWindow.idl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "domstubs.idl"

interface nsIFrameRequestCallback;
interface nsIControllers;
interface nsIDOMBlob;
interface nsIDOMLocation;
interface nsIDOMMediaQueryList;
interface nsIDOMOfflineResourceList;
interface nsIDOMStorage;
interface nsIPrompt;
interface nsISelection;
interface nsIVariant;

/**
 * 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(be62660a-e3f6-409c-a4a9-378364a9526f)]
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 */
  /* BarProp */
  readonly attribute nsISupports                        locationbar;

  /* [replaceable] menubar */
  /* BarProp */
  readonly attribute nsISupports                        menubar;

  /* [replaceable] personalbar */
  /* BarProp */
  readonly attribute nsISupports                        personalbar;

  /**
   * Accessor for the object that controls whether or not scrollbars
   * are shown in this window.
   *
   * This attribute is "replaceable" in JavaScript
   */
  /* BarProp */
  readonly attribute nsISupports                        scrollbars;

  /* [replaceable] statusbar */
  /* BarProp */
  readonly attribute nsISupports                        statusbar;

  /* [replaceable] toolbar */
  /* BarProp */
  readonly attribute nsISupports                        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([optional, Null(Stringify)] in DOMString text);
  boolean                   confirm([optional] 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();

  [optional_argc]
  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,
                     [optional] in jsval transfer);


  // 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);
  nsIDOMCSSStyleDeclaration getDefaultComputedStyle(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;

  readonly attribute nsIDOMCrypto                       crypto;
  readonly attribute nsIDOMPkcs11                       pkcs11;

  // XXX Shouldn't this be in nsIDOMChromeWindow?
  /* [replaceable] controllers */
  readonly attribute nsIControllers                     controllers;

  readonly attribute float                              mozInnerScreenX;
  readonly attribute float                              mozInnerScreenY;
  readonly attribute float                              devicePixelRatio;

  /* 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);
  // jsval because we want a WebIDL callback here
  [implicit_jscontext]
  long requestAnimationFrame(in jsval 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);
  void cancelAnimationFrame(in long aHandle);

  /**
   * The current animation start time in milliseconds since the epoch.
   */
  readonly attribute long long mozAnimationStartTime;

  /**
   * 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 ondeviceproximity;
  [implicit_jscontext] attribute jsval onuserproximity;
  [implicit_jscontext] attribute jsval ondevicelight;

  [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 nsISupports performance;
};

/**
 * Empty interface for compatibility with older versions.
 * @deprecated Use nsIDOMWindow instead
 */
[scriptable, uuid(ad5768c7-8668-4cd4-bcac-3d0a400d50be)]
interface nsIDOMWindowInternal : nsIDOMWindow {};