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