WebCore/khtml/dom/dom_node.h

   1 /*
   2  * This file is part of the DOM implementation for KDE.
   3  *
   4  * (C) 1999 Lars Knoll (knoll@kde.org)
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public License
  17  * along with this library; see the file COPYING.LIB.  If not, write to
  18  * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  *
  21  * This file includes excerpts from the Document Object Model (DOM)
  22  * Level 1 Specification (Recommendation)
  23  * http://www.w3.org/TR/REC-DOM-Level-1/
  24  * Copyright © World Wide Web Consortium , (Massachusetts Institute of
  25  * Technology , Institut National de Recherche en Informatique et en
  26  * Automatique , Keio University ). All Rights Reserved.
  27  *
  28  */
  29 #ifndef _DOM_Node_h_
  30 #define _DOM_Node_h_
  31
  32 #include <qstring.h>
  33
  34 class QRect;
  35
  36 namespace DOM {
  37
  38 class Node;
  39 class DOMString;
  40 class NodeImpl;
  41 class NamedNodeMapImpl;
  42 class EventListener;
  43 class Event;
  44
  45 /**
  46  * Objects implementing the <code> NamedNodeMap </code> interface are
  47  * used to represent collections of nodes that can be accessed by
  48  * name. Note that <code> NamedNodeMap </code> does not inherit from
  49  * <code> NodeList </code> ; <code> NamedNodeMap </code> s are not
  50  * maintained in any particular order. Objects contained in an object
  51  * implementing <code> NamedNodeMap </code> may also be accessed by an
  52  * ordinal index, but this is simply to allow convenient enumeration
  53  * of the contents of a <code> NamedNodeMap </code> , and does not
  54  * imply that the DOM specifies an order to these Nodes.
  55  *
  56  */
  57 class NamedNodeMap
  58 {
  59 public:
  60     NamedNodeMap();
  61     NamedNodeMap(const NamedNodeMap &other);
  62
  63     NamedNodeMap & operator = (const NamedNodeMap &other);
  64
  65     ~NamedNodeMap();
  66
  67     /**
  68      * The number of nodes in the map. The range of valid child node
  69      * indices is 0 to <code> length-1 </code> inclusive.
  70      *
  71      */
  72     unsigned long length() const;
  73
  74     /**
  75      * Retrieves a node specified by name.
  76      *
  77      * @param name Name of a node to retrieve.
  78      *
  79      * @return A <code> Node </code> (of any type) with the specified
  80      * name, or <code> null </code> if the specified name did not
  81      * identify any node in the map.
  82      *
  83      */
  84     Node getNamedItem ( const DOMString &name ) const;
  85
  86     /**
  87      * Adds a node using its <code> nodeName </code> attribute.
  88      *
  89      *  As the <code> nodeName </code> attribute is used to derive the
  90      * name which the node must be stored under, multiple nodes of
  91      * certain types (those that have a "special" string value) cannot
  92      * be stored as the names would clash. This is seen as preferable
  93      * to allowing nodes to be aliased.
  94      *
  95      * @param arg A node to store in a named node map. The node will
  96      * later be accessible using the value of the <code> nodeName
  97      * </code> attribute of the node. If a node with that name is
  98      * already present in the map, it is replaced by the new one.
  99      *
 100      * @return If the new <code> Node </code> replaces an existing
 101      * node with the same name the previously existing <code> Node
 102      * </code> is returned, otherwise <code> null </code> is returned.
 103      *
 104      * @exception DOMException
 105      * WRONG_DOCUMENT_ERR: Raised if <code> arg </code> was created
 106      * from a different document than the one that created the <code>
 107      * NamedNodeMap </code> .
 108      *
 109      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this <code>
 110      * NamedNodeMap </code> is readonly.
 111      *
 112      *  INUSE_ATTRIBUTE_ERR: Raised if <code> arg </code> is an <code>
 113      * Attr </code> that is already an attribute of another <code>
 114      * Element </code> object. The DOM user must explicitly clone
 115      * <code> Attr </code> nodes to re-use them in other elements.
 116      *
 117      */
 118     Node setNamedItem ( const Node &arg );
 119
 120     /**
 121      * Removes a node specified by name. If the removed node is an
 122      * <code> Attr </code> with a default value it is immediately
 123      * replaced.
 124      *
 125      * @param name The name of a node to remove.
 126      *
 127      * @return The node removed from the map or <code> null </code> if
 128      * no node with such a name exists.
 129      *
 130      * @exception DOMException
 131      * NOT_FOUND_ERR: Raised if there is no node named <code> name
 132      * </code> in the map.
 133      *
 134      */
 135     Node removeNamedItem ( const DOMString &name );
 136
 137     /**
 138      * Returns the <code> index </code> th item in the map. If <code>
 139      * index </code> is greater than or equal to the number of nodes
 140      * in the map, this returns <code> null </code> .
 141      *
 142      * @param index Index into the map.
 143      *
 144      * @return The node at the <code> index </code> th position in the
 145      * <code> NamedNodeMap </code> , or <code> null </code> if that is
 146      * not a valid index.
 147      *
 148      */
 149     Node item ( unsigned long index ) const;
 150
 151     /**
 152      * Introduced in DOM Level 2
 153      *
 154      * Retrieves a node specified by local name and namespace URI. HTML-only
 155      * DOM implementations do not need to implement this method.
 156      *
 157      * @param namespaceURI The namespace URI of the node to retrieve.
 158      *
 159      * @param localName The local name of the node to retrieve.
 160      *
 161      * @return A Node (of any type) with the specified local name and namespace
 162      * URI, or null if they do not identify any node in this map.
 163      */
 164     Node getNamedItemNS( const DOMString &namespaceURI,
 165                          const DOMString &localName ) const;
 166
 167     /**
 168      * Introduced in DOM Level 2
 169      *
 170      * Adds a node using its namespaceURI and localName. If a node with that
 171      * namespace URI and that local name is already present in this map, it is
 172      * replaced by the new one.
 173      * HTML-only DOM implementations do not need to implement this method.
 174      *
 175      * @param arg A node to store in this map. The node will later be
 176      * accessible using the value of its namespaceURI and localName attributes.
 177      *
 178      * @return If the new Node replaces an existing node the replaced Node is
 179      * returned, otherwise null is returned.
 180      *
 181      * @exception DOMException
 182      * WRONG_DOCUMENT_ERR: Raised if arg was created from a different document
 183      * than the one that created this map.
 184      *
 185      * NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
 186      *
 187      * INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an
 188      * attribute of another Element object. The DOM user must explicitly clone
 189      * Attr nodes to re-use them in other elements.
 190      */
 191     Node setNamedItemNS( const Node &arg );
 192
 193     /**
 194      * Introduced in DOM Level 2
 195      *
 196      * Removes a node specified by local name and namespace URI. A removed
 197      * attribute may be known to have a default value when this map contains
 198      * the attributes attached to an element, as returned by the attributes
 199      * attribute of the Node interface. If so, an attribute immediately appears
 200      * containing the default value as well as the corresponding namespace URI,
 201      * local name, and prefix when applicable.
 202      * HTML-only DOM implementations do not need to implement this method.
 203      *
 204      * @param namespaceURI The namespace URI of the node to remove.
 205      *
 206      * @param localName The local name of the node to remove.
 207      *
 208      * @return The node removed from this map if a node with such a local name
 209      * and namespace URI exists.
 210      *
 211      * @exception DOMException
 212      * NOT_FOUND_ERR: Raised if there is no node with the specified
 213      * namespaceURI and localName in this map.
 214      *
 215      * NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
 216      */
 217     Node removeNamedItemNS( const DOMString &namespaceURI,
 218                             const DOMString &localName );
 219
 220     /**
 221      * @internal
 222      * not part of the DOM
 223      */
 224     NamedNodeMapImpl *handle() const throw();
 225     bool isNull() const throw();
 226
 227 protected:
 228     NamedNodeMap( NamedNodeMapImpl *i);
 229     NamedNodeMapImpl *impl;
 230
 231     friend class Node;
 232     friend class DocumentType;
 233     friend class NodeImpl;
 234 #if APPLE_CHANGES
 235     friend class NamedNodeMapImpl;
 236 #endif
 237 };
 238
 239 class NamedNodeMap;
 240 class NodeList;
 241 class Document;
 242 class DOMString;
 243 class StyleSheet;
 244
 245 class NodeImpl;
 246
 247 /**
 248  * The <code> Node </code> interface is the primary datatype for the
 249  * entire Document Object Model. It represents a single node in the
 250  * document tree. While all objects implementing the <code> Node
 251  * </code> interface expose methods for dealing with children, not all
 252  * objects implementing the <code> Node </code> interface may have
 253  * children. For example, <code> Text </code> nodes may not have
 254  * children, and adding children to such nodes results in a <code>
 255  * DOMException </code> being raised.
 256  *
 257  *  The attributes <code> nodeName </code> , <code> nodeValue </code>
 258  * and <code> attributes </code> are included as a mechanism to get at
 259  * node information without casting down to the specific derived
 260  * interface. In cases where there is no obvious mapping of these
 261  * attributes for a specific <code> nodeType </code> (e.g., <code>
 262  * nodeValue </code> for an Element or <code> attributes </code> for a
 263  * Comment), this returns <code> null </code> . Note that the
 264  * specialized interfaces may contain additional and more convenient
 265  * mechanisms to get and set the relevant information.
 266  *
 267  */
 268 class Node
 269 {
 270     friend class NamedNodeMap;
 271     friend class NodeList;
 272     friend class HTMLCollection;
 273     friend class StyleSheet;
 274
 275 public:
 276     Node();
 277     Node(const Node &other);
 278
 279     /**
 280      * @internal
 281      */
 282     Node( NodeImpl *_impl);
 283
 284     Node & operator = (const Node &other);
 285
 286     bool operator == (const Node &other);
 287
 288     bool operator != (const Node &other);
 289
 290     virtual ~Node();
 291     /**
 292      * An integer indicating which type of node this is.
 293      *
 294      *
 295      * <p>The values of <code>nodeName</code>, <code>nodeValue</code>,
 296      *  and <code>attributes</code> vary according to the node type as follows:
 297      *   <table  border="1">
 298      *     <tbody>
 299      *     <tr>
 300      *       <td></td>
 301      *       <td>nodeName</td>
 302      *       <td>nodeValue</td>
 303      *       <td>attributes</td>
 304      *     </tr>
 305      *     <tr>
 306      *       <td>Element</td>
 307      *       <td>tagName</td>
 308      *       <td>null</td>
 309      *       <td>NamedNodeMap</td>
 310      *     </tr>
 311      *     <tr>
 312      *       <td>Attr</td>
 313      *       <td>name of attribute</td>
 314      *       <td>value of attribute</td>
 315      *       <td>null</td>
 316      *     </tr>
 317      *     <tr>
 318      *       <td>Text</td>
 319      *       <td>#text</td>
 320      *       <td>content of the text node</td>
 321      *       <td>null</td>
 322      *     </tr>
 323      *     <tr>
 324      *       <td>CDATASection</td>
 325      *       <td>#cdata-section</td>
 326      *       <td>content of the CDATA Section</td>
 327      *       <td>null</td>
 328      *     </tr>
 329      *     <tr>
 330      *       <td>EntityReference</td>
 331      *       <td>name of entity referenced</td>
 332      *       <td>null</td>
 333      *       <td>null</td>
 334      *       </tr>
 335      *     <tr>
 336      *       <td>Entity</td>
 337      *       <td>entity name</td>
 338      *       <td>null</td>
 339      *       <td>null</td>
 340      *     </tr>
 341      *     <tr>
 342      *       <td>ProcessingInstruction</td>
 343      *       <td>target</td>
 344      *       <td>entire content excluding the target</td>
 345      *       <td>null</td>
 346      *     </tr>
 347      *     <tr>
 348      *       <td>Comment</td>
 349      *       <td>#comment</td>
 350      *       <td>content of the comment</td>
 351      *       <td>null</td>
 352      *     </tr>
 353      *     <tr>
 354      *       <td>Document</td>
 355      *       <td>#document</td>
 356      *       <td>null</td>
 357      *       <td>null</td>
 358      *     </tr>
 359      *     <tr>
 360      *       <td>DocumentType</td>
 361      *       <td>document type name</td>
 362      *       <td>null</td>
 363      *       <td>null</td>
 364      *     </tr>
 365      *     <tr>
 366      *       <td>DocumentFragment</td>
 367      *       <td>#document-fragment</td>
 368      *       <td>null</td>
 369      *       <td>null</td>
 370      *     </tr>
 371      *     <tr>
 372      *       <td>Notation</td>
 373      *       <td>notation name</td>
 374      *       <td>null</td>
 375      *       <td>null</td>
 376      *     </tr>
 377      *     </tbody>
 378      *   </table>
 379      * </p>
 380      */
 381     enum NodeType {
 382         ELEMENT_NODE = 1,
 383         ATTRIBUTE_NODE = 2,
 384         TEXT_NODE = 3,
 385         CDATA_SECTION_NODE = 4,
 386         ENTITY_REFERENCE_NODE = 5,
 387         ENTITY_NODE = 6,
 388         PROCESSING_INSTRUCTION_NODE = 7,
 389         COMMENT_NODE = 8,
 390         DOCUMENT_NODE = 9,
 391         DOCUMENT_TYPE_NODE = 10,
 392         DOCUMENT_FRAGMENT_NODE = 11,
 393         NOTATION_NODE = 12
 394     };
 395
 396     /**
 397      * The name of this node, depending on its type; see the table
 398      * above.
 399      *
 400      */
 401     DOMString nodeName() const;
 402
 403     /**
 404      * The value of this node, depending on its type; see the table
 405      * above.
 406      *
 407      * @exception DOMException
 408      * DOMSTRING_SIZE_ERR: Raised when it would return more characters
 409      * than fit in a <code> DOMString </code> variable on the
 410      * implementation platform.
 411      *
 412      */
 413     DOMString nodeValue() const;
 414
 415     /**
 416      * see @ref nodeValue
 417      * @exception DOMException
 418      * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
 419      *
 420      */
 421     void setNodeValue( const DOMString & );
 422
 423     /**
 424      * A code representing the type of the underlying object, as
 425      * defined above.
 426      *
 427      */
 428     unsigned short nodeType() const;
 429
 430     /**
 431      * The parent of this node. All nodes, except <code> Document
 432      * </code> , <code> DocumentFragment </code> , and <code> Attr
 433      * </code> may have a parent. However, if a node has just been
 434      * created and not yet added to the tree, or if it has been
 435      * removed from the tree, this is <code> null </code> .
 436      *
 437      */
 438     Node parentNode() const;
 439
 440     /**
 441      * A <code> NodeList </code> that contains all children of this
 442      * node. If there are no children, this is a <code> NodeList
 443      * </code> containing no nodes. The content of the returned <code>
 444      * NodeList </code> is &quot;live&quot; in the sense that, for
 445      * instance, changes to the children of the node object that it
 446      * was created from are immediately reflected in the nodes
 447      * returned by the <code> NodeList </code> accessors; it is not a
 448      * static snapshot of the content of the node. This is true for
 449      * every <code> NodeList </code> , including the ones returned by
 450      * the <code> getElementsByTagName </code> method.
 451      *
 452      */
 453     NodeList childNodes() const;
 454
 455     /**
 456      * The first child of this node. If there is no such node, this
 457      * returns <code> null </code> .
 458      *
 459      */
 460     Node firstChild() const;
 461
 462     /**
 463      * The last child of this node. If there is no such node, this
 464      * returns <code> null </code> .
 465      *
 466      */
 467     Node lastChild() const;
 468
 469     /**
 470      * The node immediately preceding this node. If there is no such
 471      * node, this returns <code> null </code> .
 472      *
 473      */
 474     Node previousSibling() const;
 475
 476     /**
 477      * The node immediately following this node. If there is no such
 478      * node, this returns <code> null </code> .
 479      *
 480      */
 481     Node nextSibling() const;
 482
 483     /**
 484      * A <code> NamedNodeMap </code> containing the attributes of this
 485      * node (if it is an <code> Element </code> ) or <code> null
 486      * </code> otherwise.
 487      *
 488      */
 489     NamedNodeMap attributes() const;
 490
 491     /**
 492      * The <code> Document </code> object associated with this node.
 493      * This is also the <code> Document </code> object used to create
 494      * new nodes. When this node is a <code> Document </code> this is
 495      * <code> null </code> .
 496      *
 497      */
 498     Document ownerDocument() const;
 499
 500     /**
 501      * Inserts the node <code> newChild </code> before the existing
 502      * child node <code> refChild </code> . If <code> refChild </code>
 503      * is <code> null </code> , insert <code> newChild </code> at the
 504      * end of the list of children.
 505      *
 506      *  If <code> newChild </code> is a <code> DocumentFragment
 507      * </code> object, all of its children are inserted, in the same
 508      * order, before <code> refChild </code> . If the <code> newChild
 509      * </code> is already in the tree, it is first removed.
 510      *
 511      * @param newChild The node to insert.
 512      *
 513      * @param refChild The reference node, i.e., the node before which
 514      * the new node must be inserted.
 515      *
 516      * @return The node being inserted.
 517      *
 518      * @exception DOMException
 519      * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that
 520      * does not allow children of the type of the <code> newChild
 521      * </code> node, or if the node to insert is one of this node's
 522      * ancestors.
 523      *
 524      *  WRONG_DOCUMENT_ERR: Raised if <code> newChild </code> was
 525      * created from a different document than the one that created
 526      * this node.
 527      *
 528      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 529      *
 530      *  NOT_FOUND_ERR: Raised if <code> refChild </code> is not a
 531      * child of this node.
 532      *
 533      */
 534     Node insertBefore ( const Node &newChild, const Node &refChild );
 535
 536     /**
 537      * Replaces the child node <code> oldChild </code> with <code>
 538      * newChild </code> in the list of children, and returns the
 539      * <code> oldChild </code> node. If the <code> newChild </code> is
 540      * already in the tree, it is first removed.
 541      *
 542      * @param newChild The new node to put in the child list.
 543      *
 544      * @param oldChild The node being replaced in the list.
 545      *
 546      * @return The node replaced.
 547      *
 548      * @exception DOMException
 549      * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that
 550      * does not allow children of the type of the <code> newChild
 551      * </code> node, or it the node to put in is one of this node's
 552      * ancestors.
 553      *
 554      *  WRONG_DOCUMENT_ERR: Raised if <code> newChild </code> was
 555      * created from a different document than the one that created
 556      * this node.
 557      *
 558      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 559      *
 560      *  NOT_FOUND_ERR: Raised if <code> oldChild </code> is not a
 561      * child of this node.
 562      *
 563      */
 564     Node replaceChild ( const Node &newChild, const Node &oldChild );
 565
 566     /**
 567      * Removes the child node indicated by <code> oldChild </code>
 568      * from the list of children, and returns it.
 569      *
 570      * @param oldChild The node being removed.
 571      *
 572      * @return The node removed.
 573      *
 574      * @exception DOMException
 575      * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 576      *
 577      *  NOT_FOUND_ERR: Raised if <code> oldChild </code> is not a
 578      * child of this node.
 579      *
 580      */
 581     Node removeChild ( const Node &oldChild );
 582
 583     /**
 584      * Adds the node <code> newChild </code> to the end of the list of
 585      * children of this node. If the <code> newChild </code> is
 586      * already in the tree, it is first removed.
 587      *
 588      * @param newChild The node to add.
 589      *
 590      *  If it is a <code> DocumentFragment </code> object, the entire
 591      * contents of the document fragment are moved into the child list
 592      * of this node
 593      *
 594      * @return The node added.
 595      *
 596      * @exception DOMException
 597      * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that
 598      * does not allow children of the type of the <code> newChild
 599      * </code> node, or if the node to append is one of this node's
 600      * ancestors.
 601      *
 602      *  WRONG_DOCUMENT_ERR: Raised if <code> newChild </code> was
 603      * created from a different document than the one that created
 604      * this node.
 605      *
 606      *  NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 607      *
 608      */
 609     Node appendChild ( const Node &newChild );
 610
 611     /**
 612      * This is a convenience method to allow easy determination of
 613      * whether a node has any children.
 614      *
 615      * @return <code> true </code> if the node has any children,
 616      * <code> false </code> if the node has no children.
 617      *
 618      */
 619     bool hasChildNodes (  );
 620
 621     /**
 622      * Returns a duplicate of this node, i.e., serves as a generic
 623      * copy constructor for nodes. The duplicate node has no parent (
 624      * <code> parentNode </code> returns <code> null </code> .).
 625      *
 626      *  Cloning an <code> Element </code> copies all attributes and
 627      * their values, including those generated by the XML processor to
 628      * represent defaulted attributes, but this method does not copy
 629      * any text it contains unless it is a deep clone, since the text
 630      * is contained in a child <code> Text </code> node. Cloning any
 631      * other type of node simply returns a copy of this node.
 632      *
 633      * @param deep If <code> true </code> , recursively clone the
 634      * subtree under the specified node; if <code> false </code> ,
 635      * clone only the node itself (and its attributes, if it is an
 636      * <code> Element </code> ).
 637      *
 638      * @return The duplicate node.
 639      *
 640      */
 641     Node cloneNode ( bool deep );
 642
 643     /**
 644      * Modified in DOM Level 2
 645      *
 646      * Puts all Text nodes in the full depth of the sub-tree underneath this
 647      * Node, including attribute nodes, into a "normal" form where only
 648      * structure (e.g., elements, comments, processing instructions, CDATA
 649      * sections, and entity references) separates Text nodes, i.e., there are
 650      * neither adjacent Text nodes nor empty Text nodes. This can be used to
 651      * ensure that the DOM view of a document is the same as if it were saved
 652      * and re-loaded, and is useful when operations (such as XPointer
 653      * [XPointer] lookups) that depend on a particular document tree structure
 654      * are to be used.
 655      *
 656      * Note: In cases where the document contains CDATASections, the normalize
 657      * operation alone may not be sufficient, since XPointers do not
 658      * differentiate between Text nodes and CDATASection nodes.
 659      */
 660     void normalize (  );
 661
 662     /**
 663      * Introduced in DOM Level 2
 664      *
 665      * Tests whether the DOM implementation implements a specific feature and
 666      * that feature is supported by this node.
 667      *
 668      * @param feature The name of the feature to test. This is the same name
 669      * which can be passed to the method hasFeature on DOMImplementation.
 670      *
 671      * @param version This is the version number of the feature to test. In
 672      * Level 2, version 1, this is the string "2.0". If the version is not
 673      * specified, supporting any version of the feature will cause the method
 674      * to return true.
 675      *
 676      * @return Returns true if the specified feature is supported on this node,
 677      * false otherwise.
 678      */
 679     bool isSupported( const DOMString &feature,
 680                       const DOMString &version ) const;
 681
 682     /**
 683      * Introduced in DOM Level 2
 684      *
 685      * The namespace URI of this node, or null if it is unspecified.
 686      * This is not a computed value that is the result of a namespace lookup
 687      * based on an examination of the namespace declarations in scope. It is
 688      * merely the namespace URI given at creation time. For nodes of any type
 689      * other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM
 690      * Level 1 method, such as createElement from the Document interface, this
 691      * is always null.
 692      *
 693      * Note: Per the Namespaces in XML Specification [Namespaces] an attribute
 694      * does not inherit its namespace from the element it is attached to. If an
 695      * attribute is not explicitly given a namespace, it simply has no
 696      * namespace.
 697      */
 698     DOMString namespaceURI(  ) const;
 699
 700     /**
 701      * Introduced in DOM Level 2
 702      *
 703      * The namespace prefix of this node, or null if it is unspecified.
 704      * Note that setting this attribute, when permitted, changes the nodeName
 705      * attribute, which holds the qualified name, as well as the tagName and
 706      * name attributes of the Element and Attr interfaces, when applicable.
 707      * Note also that changing the prefix of an attribute that is known to have
 708      * a default value, does not make a new attribute with the default value
 709      * and the original prefix appear, since the namespaceURI and localName do
 710      * not change.
 711      * For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and
 712      * nodes created with a DOM Level 1 method, such as createElement from the
 713      * Document interface, this is always null.
 714      */
 715     DOMString prefix(  ) const;
 716
 717     /**
 718      * see @ref prefix
 719      *
 720      * @exception DOMException
 721      * INVALID_CHARACTER_ERR: Raised if the specified prefix contains an
 722      * illegal character.
 723      *
 724      * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 725      *
 726      * NAMESPACE_ERR: Raised if the specified prefix is malformed, if the
 727      * namespaceURI of this node is null, if the specified prefix is "xml" and
 728      * the namespaceURI of this node is different from
 729      * "http://www.w3.org/XML/1998/namespace", if this node is an attribute and
 730      * the specified prefix is "xmlns" and the namespaceURI of this node is
 731      * different from "http://www.w3.org/2000/xmlns/", or if this node is an
 732      * attribute and the qualifiedName of this node is "xmlns" [Namespaces].
 733      */
 734     void setPrefix(const DOMString &prefix );
 735
 736     /**
 737      * Introduced in DOM Level 2
 738      *
 739      * Returns the local part of the qualified name of this node.
 740      * For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and
 741      * nodes created with a DOM Level 1 method, such as createElement from the
 742      * Document interface, this is always null.
 743      */
 744     DOMString localName(  ) const;
 745
 746     /**
 747      * Returns whether this node (if it is an element) has any attributes.
 748      * @return a boolean. True if this node has any attributes, false otherwise.
 749      *  Introduced in DOM Level 2
 750      */
 751     bool hasAttributes (  );
 752
 753     /**
 754      * Introduced in DOM Level 2
 755      * This method is from the EventTarget interface
 756      *
 757      * This method allows the registration of event listeners on the event
 758      * target. If an EventListener is added to an EventTarget while it is
 759      * processing an event, it will not be triggered by the current actions but
 760      * may be triggered during a later stage of event flow, such as the
 761      * bubbling phase.
 762      *
 763      * If multiple identical EventListeners are registered on the same
 764      * EventTarget with the same parameters the duplicate instances are
 765      * discarded. They do not cause the EventListener to be called twice and
 766      * since they are discarded they do not need to be removed with the
 767      * removeEventListener method. Parameters
 768      *
 769      * @param type The event type for which the user is registering
 770      *
 771      * @param listener The listener parameter takes an interface implemented by
 772      * the user which contains the methods to be called when the event occurs.
 773      *
 774      * @param useCapture If true, useCapture indicates that the user wishes to
 775      * initiate capture. After initiating capture, all events of the specified
 776      * type will be dispatched to the registered EventListener before being
 777      * dispatched to any EventTargets beneath them in the tree. Events which
 778      * are bubbling upward through the tree will not trigger an EventListener
 779      * designated to use capture.
 780      */
 781     void addEventListener(const DOMString &type,
 782                           EventListener *listener,
 783                           const bool useCapture);
 784
 785     /**
 786      * Introduced in DOM Level 2
 787      * This method is from the EventTarget interface
 788      *
 789      * This method allows the removal of event listeners from the event target.
 790      * If an EventListener is removed from an EventTarget while it is
 791      * processing an event, it will not be triggered by the current actions.
 792      *
 793      * EventListeners can never be invoked after being removed.
 794      *
 795      * Calling removeEventListener with arguments which do not identify any
 796      * currently registered EventListener on the EventTarget has no effect.
 797      *
 798      * @param type Specifies the event type of the EventListener being removed.
 799      *
 800      * @param listener The EventListener parameter indicates the EventListener
 801      * to be removed.
 802      *
 803      * @param useCapture Specifies whether the EventListener being removed was
 804      * registered as a capturing listener or not. If a listener was registered
 805      * twice, one with capture and one without, each must be removed
 806      * separately. Removal of a capturing listener does not affect a
 807      * non-capturing version of the same listener, and vice versa.
 808      */
 809
 810     void removeEventListener(const DOMString &type,
 811                              EventListener *listener,
 812                              bool useCapture);
 813
 814     /**
 815      * Introduced in DOM Level 2
 816      * This method is from the EventTarget interface
 817      *
 818      * This method allows the dispatch of events into the implementations event
 819      * model. Events dispatched in this manner will have the same capturing and
 820      * bubbling behavior as events dispatched directly by the implementation.
 821      * The target of the event is the EventTarget on which dispatchEvent is
 822      * called.
 823      *
 824      * @param evt Specifies the event type, behavior, and contextual
 825      * information to be used in processing the event.
 826      *
 827      * @return The return value of dispatchEvent indicates whether any of the
 828      * listeners which handled the event called preventDefault. If
 829      * preventDefault was called the value is false, else the value is true.
 830      *
 831      * @exception EventException
 832      * UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event's type was not specified
 833      * by initializing the event before dispatchEvent was called. Specification
 834      * of the Event's type as null or an empty string will also trigger this
 835      * exception.
 836      */
 837     bool dispatchEvent(const Event &evt);
 838
 839     /**
 840      * @internal
 841      * not part of the DOM.
 842      * @returns the element id, in case this is an element, 0 otherwise
 843      */
 844     Q_UINT32 elementId() const;
 845
 846     /**
 847      * tests if this Node is 0. Useful especially, if casting to a derived
 848      * class:
 849      *
 850      * <pre>
 851      * Node n = .....;
 852      * // try to convert into an Element:
 853      * Element e = n;
 854      * if( e.isNull() )
 855      *   kdDebug(300) << "node isn't an element node" << endl;
 856      * </pre>
 857      */
 858     bool isNull() const;
 859
 860     /**
 861      * @internal handle to the implementation object
 862      */
 863     NodeImpl *handle() const;
 864
 865     /**
 866      * @internal returns the index of a node
 867      */
 868     unsigned long index() const;
 869     QString toHTML();
 870     void applyChanges();
 871     /**
 872      * not part of the DOM.
 873      * @returns the exact coordinates and size of this element.
 874      */
 875     QRect getRect();
 876
 877     /**
 878      * not part of the DOM.
 879      * @returns whether this node is contenteditable.
 880      */
 881     bool isContentEditable() const;
 882
 883 protected:
 884     NodeImpl *impl;
 885 };
 886
 887
 888 class NodeListImpl;
 889
 890 /**
 891  * The <code> NodeList </code> interface provides the abstraction of
 892  * an ordered collection of nodes, without defining or constraining
 893  * how this collection is implemented.
 894  *
 895  *  The items in the <code> NodeList </code> are accessible via an
 896  * integral index, starting from 0.
 897  *
 898  */
 899 class NodeList
 900 {
 901     friend class Element;
 902     friend class Node;
 903     friend class Document;
 904     friend class HTMLDocument;
 905 #if APPLE_CHANGES
 906     friend class NodeListImpl;
 907 #endif
 908
 909 public:
 910     NodeList();
 911     NodeList(const NodeList &other);
 912
 913     NodeList & operator = (const NodeList &other);
 914
 915     ~NodeList();
 916
 917     /**
 918      * The number of nodes in the list. The range of valid child node
 919      * indices is 0 to <code> length-1 </code> inclusive.
 920      *
 921      */
 922     unsigned long length() const;
 923
 924     /**
 925      * Returns the <code> index </code> th item in the collection. If
 926      * <code> index </code> is greater than or equal to the number of
 927      * nodes in the list, this returns <code> null </code> .
 928      *
 929      * @param index Index into the collection.
 930      *
 931      * @return The node at the <code> index </code> th position in the
 932      * <code> NodeList </code> , or <code> null </code> if that is not
 933      * a valid index.
 934      *
 935      */
 936     Node item ( unsigned long index ) const;
 937
 938     /**
 939      * @internal
 940      * not part of the DOM
 941      */
 942     Node itemById (const DOMString& elementId) const;
 943
 944     NodeListImpl *handle() const;
 945     bool isNull() const;
 946
 947
 948 protected:
 949     NodeList(const NodeListImpl *i);
 950     NodeListImpl *impl;
 951 };
 952
 953
 954
 955 /**
 956  * A DOMTimeStamp represents a number of milliseconds.
 957  *
 958  */
 959 typedef unsigned long long DOMTimeStamp;
 960
 961
 962 }; //namespace
 963 #endif