dom/webidl/Document.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  * http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/core/nsIDOMDocument.idl
   7  */
   8
   9 interface WindowProxy;
  10 interface nsISupports;
  11 interface URI;
  12 interface nsIDocShell;
  13
  14 enum VisibilityState { "hidden", "visible" };
  15
  16 /* http://dom.spec.whatwg.org/#interface-document */
  17 [Constructor]
  18 interface Document : Node {
  19   [Throws]
  20   readonly attribute DOMImplementation implementation;
  21   [Pure]
  22   readonly attribute DOMString URL;
  23   [Pure]
  24   readonly attribute DOMString documentURI;
  25   [Pure]
  26   readonly attribute DOMString compatMode;
  27   [Pure]
  28   readonly attribute DOMString characterSet;
  29   [Pure]
  30   readonly attribute DOMString contentType;
  31
  32   [Pure]
  33   readonly attribute DocumentType? doctype;
  34   [Pure]
  35   readonly attribute Element? documentElement;
  36   [Pure]
  37   HTMLCollection getElementsByTagName(DOMString localName);
  38   [Pure, Throws]
  39   HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  40   [Pure]
  41   HTMLCollection getElementsByClassName(DOMString classNames);
  42   [Pure]
  43   Element? getElementById(DOMString elementId);
  44
  45   [NewObject, Throws]
  46   Element createElement(DOMString localName);
  47   [NewObject, Throws]
  48   Element createElementNS(DOMString? namespace, DOMString qualifiedName);
  49   [NewObject]
  50   DocumentFragment createDocumentFragment();
  51   [NewObject]
  52   Text createTextNode(DOMString data);
  53   [NewObject]
  54   Comment createComment(DOMString data);
  55   [NewObject, Throws]
  56   ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);
  57
  58   [Throws]
  59   Node importNode(Node node, optional boolean deep = false);
  60   [Throws]
  61   Node adoptNode(Node node);
  62
  63   [NewObject, Throws]
  64   Event createEvent(DOMString interface);
  65
  66   [NewObject, Throws]
  67   Range createRange();
  68
  69   // NodeFilter.SHOW_ALL = 0xFFFFFFFF
  70   [NewObject, Throws]
  71   NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
  72   [NewObject, Throws]
  73   TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = 0xFFFFFFFF, optional NodeFilter? filter = null);
  74
  75   // NEW
  76   // No support for prepend/append yet
  77   // void prepend((Node or DOMString)... nodes);
  78   // void append((Node or DOMString)... nodes);
  79
  80   // These are not in the spec, but leave them for now for backwards compat.
  81   // So sort of like Gecko extensions
  82   [NewObject, Throws]
  83   CDATASection createCDATASection(DOMString data);
  84   [NewObject, Throws]
  85   Attr createAttribute(DOMString name);
  86   [NewObject, Throws]
  87   Attr createAttributeNS(DOMString? namespace, DOMString name);
  88   [Pure]
  89   readonly attribute DOMString? inputEncoding;
  90 };
  91
  92 // http://www.whatwg.org/specs/web-apps/current-work/#the-document-object
  93 partial interface Document {
  94   [PutForwards=href, Unforgeable] readonly attribute Location? location;
  95   //(HTML only)         attribute DOMString domain;
  96   readonly attribute DOMString referrer;
  97   //(HTML only)         attribute DOMString cookie;
  98   readonly attribute DOMString lastModified;
  99   readonly attribute DOMString readyState;
 100
 101   // DOM tree accessors
 102   //(Not proxy yet)getter object (DOMString name);
 103   [SetterThrows, Pure]
 104            attribute DOMString title;
 105   [Pure]
 106            attribute DOMString dir;
 107   //(HTML only)         attribute HTMLElement? body;
 108   //(HTML only)readonly attribute HTMLHeadElement? head;
 109   //(HTML only)readonly attribute HTMLCollection images;
 110   //(HTML only)readonly attribute HTMLCollection embeds;
 111   //(HTML only)readonly attribute HTMLCollection plugins;
 112   //(HTML only)readonly attribute HTMLCollection links;
 113   //(HTML only)readonly attribute HTMLCollection forms;
 114   //(HTML only)readonly attribute HTMLCollection scripts;
 115   //(HTML only)NodeList getElementsByName(DOMString elementName);
 116   //(HTML only)NodeList getItems(optional DOMString typeNames); // microdata
 117   //(Not implemented)readonly attribute DOMElementMap cssElementMap;
 118
 119   // dynamic markup insertion
 120   //(HTML only)Document open(optional DOMString type, optional DOMString replace);
 121   //(HTML only)WindowProxy open(DOMString url, DOMString name, DOMString features, optional boolean replace);
 122   //(HTML only)void close();
 123   //(HTML only)void write(DOMString... text);
 124   //(HTML only)void writeln(DOMString... text);
 125
 126   // user interaction
 127   [Pure]
 128   readonly attribute WindowProxy? defaultView;
 129   readonly attribute Element? activeElement;
 130   [Throws]
 131   boolean hasFocus();
 132   //(HTML only)         attribute DOMString designMode;
 133   //(HTML only)boolean execCommand(DOMString commandId);
 134   //(HTML only)boolean execCommand(DOMString commandId, boolean showUI);
 135   //(HTML only)boolean execCommand(DOMString commandId, boolean showUI, DOMString value);
 136   //(HTML only)boolean queryCommandEnabled(DOMString commandId);
 137   //(HTML only)boolean queryCommandIndeterm(DOMString commandId);
 138   //(HTML only)boolean queryCommandState(DOMString commandId);
 139   //(HTML only)boolean queryCommandSupported(DOMString commandId);
 140   //(HTML only)DOMString queryCommandValue(DOMString commandId);
 141   //(Not implemented)readonly attribute HTMLCollection commands;
 142
 143   // special event handler IDL attributes that only apply to Document objects
 144   [LenientThis] attribute EventHandler onreadystatechange;
 145
 146   // Gecko extensions?
 147                 attribute EventHandler onwheel;
 148                 attribute EventHandler oncopy;
 149                 attribute EventHandler oncut;
 150                 attribute EventHandler onpaste;
 151                 attribute EventHandler onbeforescriptexecute;
 152                 attribute EventHandler onafterscriptexecute;
 153   /**
 154    * True if this document is synthetic : stand alone image, video, audio file,
 155    * etc.
 156    */
 157   [Func="IsChromeOrXBL"] readonly attribute boolean mozSyntheticDocument;
 158   /**
 159    * Returns the script element whose script is currently being processed.
 160    *
 161    * @see <https://developer.mozilla.org/en/DOM/document.currentScript>
 162    */
 163   [Pure]
 164   readonly attribute Element? currentScript;
 165   /**
 166    * Release the current mouse capture if it is on an element within this
 167    * document.
 168    *
 169    * @see <https://developer.mozilla.org/en/DOM/document.releaseCapture>
 170    */
 171   void releaseCapture();
 172   /**
 173    * Use the given DOM element as the source image of target |-moz-element()|.
 174    *
 175    * This function introduces a new special ID (called "image element ID"),
 176    * which is only used by |-moz-element()|, and associates it with the given
 177    * DOM element.  Image elements ID's have the higher precedence than general
 178    * HTML id's, so if |document.mozSetImageElement(<id>, <element>)| is called,
 179    * |-moz-element(#<id>)| uses |<element>| as the source image even if there
 180    * is another element with id attribute = |<id>|.  To unregister an image
 181    * element ID |<id>|, call |document.mozSetImageElement(<id>, null)|.
 182    *
 183    * Example:
 184    * <script>
 185    *   canvas = document.createElement("canvas");
 186    *   canvas.setAttribute("width", 100);
 187    *   canvas.setAttribute("height", 100);
 188    *   // draw to canvas
 189    *   document.mozSetImageElement("canvasbg", canvas);
 190    * </script>
 191    * <div style="background-image: -moz-element(#canvasbg);"></div>
 192    *
 193    * @param aImageElementId an image element ID to associate with
 194    * |aImageElement|
 195    * @param aImageElement a DOM element to be used as the source image of
 196    * |-moz-element(#aImageElementId)|. If this is null, the function will
 197    * unregister the image element ID |aImageElementId|.
 198    *
 199    * @see <https://developer.mozilla.org/en/DOM/document.mozSetImageElement>
 200    */
 201   void mozSetImageElement(DOMString aImageElementId,
 202                           Element? aImageElement);
 203
 204   [ChromeOnly]
 205   readonly attribute URI? documentURIObject;
 206
 207 };
 208
 209 // http://dvcs.w3.org/hg/fullscreen/raw-file/tip/Overview.html#api
 210 partial interface Document {
 211   // Note: Per spec the 'S' in these two is lowercase, but the "Moz"
 212   // versions hve it uppercase.
 213   readonly attribute boolean mozFullScreenEnabled;
 214   [Throws]
 215   readonly attribute Element? mozFullScreenElement;
 216
 217   //(Renamed?)void exitFullscreen();
 218
 219   // Gecko-specific fullscreen bits
 220   readonly attribute boolean mozFullScreen;
 221   void mozCancelFullScreen();
 222 };
 223
 224 // http://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html#extensions-to-the-document-interface
 225 partial interface Document {
 226     readonly attribute Element? mozPointerLockElement;
 227     void mozExitPointerLock ();
 228 };
 229
 230 //http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/index.html#dfn-document-register
 231 partial interface Document {
 232     [Throws, Func="nsDocument::IsWebComponentsEnabled"]
 233     object registerElement(DOMString name, optional ElementRegistrationOptions options);
 234 };
 235
 236 //http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/index.html#dfn-document-register
 237 partial interface Document {
 238     [NewObject, Throws]
 239     Element createElement(DOMString localName, DOMString typeExtension);
 240     [NewObject, Throws]
 241     Element createElementNS(DOMString? namespace, DOMString qualifiedName, DOMString typeExtension);
 242 };
 243
 244 // http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html#sec-document-interface
 245 partial interface Document {
 246   readonly attribute boolean hidden;
 247   readonly attribute boolean mozHidden;
 248   readonly attribute VisibilityState visibilityState;
 249   readonly attribute VisibilityState mozVisibilityState;
 250 };
 251
 252 // http://dev.w3.org/csswg/cssom/#extensions-to-the-document-interface
 253 partial interface Document {
 254     [Constant]
 255     readonly attribute StyleSheetList styleSheets;
 256     attribute DOMString? selectedStyleSheetSet;
 257     readonly attribute DOMString? lastStyleSheetSet;
 258     readonly attribute DOMString? preferredStyleSheetSet;
 259     [Constant]
 260     readonly attribute DOMStringList styleSheetSets;
 261     void enableStyleSheetsForSet (DOMString? name);
 262 };
 263
 264 // http://dev.w3.org/csswg/cssom-view/#extensions-to-the-document-interface
 265 partial interface Document {
 266     Element? elementFromPoint (float x, float y);
 267
 268     CaretPosition? caretPositionFromPoint (float x, float y);
 269 };
 270
 271 // http://dvcs.w3.org/hg/undomanager/raw-file/tip/undomanager.html
 272 partial interface Document {
 273     [Pref="dom.undo_manager.enabled"]
 274     readonly attribute UndoManager? undoManager;
 275 };
 276
 277 // http://dev.w3.org/2006/webapi/selectors-api2/#interface-definitions
 278 partial interface Document {
 279   [Throws, Pure]
 280   Element?  querySelector(DOMString selectors);
 281   [Throws, Pure]
 282   NodeList  querySelectorAll(DOMString selectors);
 283
 284   //(Not implemented)Element?  find(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
 285   //(Not implemented)NodeList  findAll(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
 286 };
 287
 288 // http://dev.w3.org/fxtf/web-animations/#extensions-to-the-document-interface
 289 partial interface Document {
 290   [Pref="dom.animations-api.core.enabled"]
 291   readonly attribute AnimationTimeline timeline;
 292 };
 293
 294 //  Mozilla extensions of various sorts
 295 partial interface Document {
 296   // nsIDOMDocumentXBL.  Wish we could make these [ChromeOnly], but
 297   // that would likely break bindings running with the page principal.
 298   [Func="IsChromeOrXBL"]
 299   NodeList? getAnonymousNodes(Element elt);
 300   [Func="IsChromeOrXBL"]
 301   Element? getAnonymousElementByAttribute(Element elt, DOMString attrName,
 302                                           DOMString attrValue);
 303   [Func="IsChromeOrXBL"]
 304   Element? getBindingParent(Node node);
 305   [Throws, Func="IsChromeOrXBL"]
 306   void loadBindingDocument(DOMString documentURL);
 307
 308   // nsIDOMDocumentTouch
 309   // XXXbz I can't find the sane spec for this stuff, so just cribbing
 310   // from our xpidl for now.
 311   [NewObject, Func="nsGenericHTMLElement::TouchEventsEnabled"]
 312   Touch createTouch(optional Window? view = null,
 313                     optional EventTarget? target = null,
 314                     optional long identifier = 0,
 315                     optional long pageX = 0,
 316                     optional long pageY = 0,
 317                     optional long screenX = 0,
 318                     optional long screenY = 0,
 319                     optional long clientX = 0,
 320                     optional long clientY = 0,
 321                     optional long radiusX = 0,
 322                     optional long radiusY = 0,
 323                     optional float rotationAngle = 0,
 324                     optional float force = 0);
 325   // XXXbz a hack to get around the fact that we don't support variadics as
 326   // distinguishing arguments yet.  Once this hack is removed. we can also
 327   // remove the corresponding overload on nsIDocument, since Touch... and
 328   // sequence<Touch> look the same in the C++.
 329   [NewObject, Func="nsGenericHTMLElement::TouchEventsEnabled"]
 330   TouchList createTouchList(Touch touch, Touch... touches);
 331   // XXXbz and another hack for the fact that we can't usefully have optional
 332   // distinguishing arguments but need a working zero-arg form of
 333   // createTouchList().
 334   [NewObject, Func="nsGenericHTMLElement::TouchEventsEnabled"]
 335   TouchList createTouchList();
 336   [NewObject, Func="nsGenericHTMLElement::TouchEventsEnabled"]
 337   TouchList createTouchList(sequence<Touch> touches);
 338
 339   [ChromeOnly]
 340   attribute boolean styleSheetChangeEventsEnabled;
 341
 342   [ChromeOnly, Throws]
 343   void obsoleteSheet(URI sheetURI);
 344   [ChromeOnly, Throws]
 345   void obsoleteSheet(DOMString sheetURI);
 346
 347   [ChromeOnly] readonly attribute nsIDocShell? docShell;
 348
 349   [ChromeOnly] readonly attribute DOMString contentLanguage;
 350 };
 351
 352 // Extension to give chrome JS the ability to determine when a document was
 353 // created to satisfy an iframe with srcdoc attribute.
 354 partial interface Document {
 355   [ChromeOnly] readonly attribute boolean isSrcdocDocument;
 356 };
 357
 358 Document implements XPathEvaluator;
 359 Document implements GlobalEventHandlers;
 360 Document implements TouchEventHandlers;
 361 Document implements ParentNode;
 362 Document implements OnErrorEventHandlerForNodes;