File indexing completed on 2024-04-28 11:37:43
0001 /* 0002 * This file is part of the DOM implementation for KDE. 0003 * 0004 * Copyright 1999 Lars Knoll (knoll@kde.org) 0005 * 0006 * This library is free software; you can redistribute it and/or 0007 * modify it under the terms of the GNU Library General Public 0008 * License as published by the Free Software Foundation; either 0009 * version 2 of the License, or (at your option) any later version. 0010 * 0011 * This library is distributed in the hope that it will be useful, 0012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0014 * Library General Public License for more details. 0015 * 0016 * You should have received a copy of the GNU Library General Public License 0017 * along with this library; see the file COPYING.LIB. If not, write to 0018 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0019 * Boston, MA 02110-1301, USA. 0020 * 0021 * This file includes excerpts from the Document Object Model (DOM) 0022 * Level 1 Specification (Recommendation) 0023 * https://www.w3.org/TR/REC-DOM-Level-1/ 0024 * Copyright © World Wide Web Consortium , (Massachusetts Institute of 0025 * Technology , Institut National de Recherche en Informatique et en 0026 * Automatique , Keio University ). All Rights Reserved. 0027 * 0028 */ 0029 #ifndef _DOM_ELEMENT_h_ 0030 #define _DOM_ELEMENT_h_ 0031 0032 #include <khtml_export.h> 0033 #include <dom/dom_node.h> 0034 #include <dom/css_value.h> 0035 0036 namespace DOM 0037 { 0038 0039 class DOMString; 0040 class AttrImpl; 0041 class Element; 0042 class ElementImpl; 0043 class NamedAttrMapImpl; 0044 class DocumentImpl; 0045 0046 /** 0047 * The \c Attr interface represents an attribute in an 0048 * \c Element object. Typically the allowable values for 0049 * the attribute are defined in a document type definition. 0050 * 0051 * \c Attr objects inherit the \c Node 0052 * interface, but since they are not actually child nodes of the 0053 * element they describe, the DOM does not consider them part of the 0054 * document tree. Thus, the \c Node attributes 0055 * \c parentNode , \c previousSibling , and 0056 * \c nextSibling have a null value for \c Attr 0057 * objects. The DOM takes the view that attributes are properties of 0058 * elements rather than having a separate identity from the elements 0059 * they are associated with; this should make it more efficient to 0060 * implement such features as default attributes associated with all 0061 * elements of a given type. Furthermore, \c Attr nodes 0062 * may not be immediate children of a \c DocumentFragment 0063 * . However, they can be associated with \c Element nodes 0064 * contained within a \c DocumentFragment . In short, 0065 * users and implementors of the DOM need to be aware that \c Attr 0066 * nodes have some things in common with other objects 0067 * inheriting the \c Node interface, but they also are 0068 * quite distinct. 0069 * 0070 * The attribute's effective value is determined as follows: if this 0071 * attribute has been explicitly assigned any value, that value is the 0072 * attribute's effective value; otherwise, if there is a declaration 0073 * for this attribute, and that declaration includes a default value, 0074 * then that default value is the attribute's effective value; 0075 * otherwise, the attribute does not exist on this element in the 0076 * structure model until it has been explicitly added. Note that the 0077 * \c nodeValue attribute on the \c Attr 0078 * instance can also be used to retrieve the string version of the 0079 * attribute's value(s). 0080 * 0081 * In XML, where the value of an attribute can contain entity 0082 * references, the child nodes of the \c Attr node provide 0083 * a representation in which entity references are not expanded. These 0084 * child nodes may be either \c Text or 0085 * \c EntityReference nodes. Because the attribute type may be 0086 * unknown, there are no tokenized attribute values. 0087 * 0088 */ 0089 class KHTML_EXPORT Attr : public Node 0090 { 0091 friend class Element; 0092 friend class Document; 0093 friend class DocumentImpl; 0094 friend class HTMLDocument; 0095 friend class ElementImpl; 0096 friend class NamedAttrMapImpl; 0097 friend class AttrImpl; 0098 0099 public: 0100 Attr(); 0101 Attr(const Node &other) : Node() 0102 { 0103 (*this) = other; 0104 } 0105 Attr(const Attr &other); 0106 0107 Attr &operator = (const Node &other); 0108 Attr &operator = (const Attr &other); 0109 0110 ~Attr(); 0111 0112 /** 0113 * Returns the name of this attribute. 0114 * 0115 */ 0116 DOMString name() const; 0117 0118 /** 0119 * If this attribute was explicitly given a value in the original 0120 * document, this is \c true ; otherwise, it is 0121 * \c false . Note that the implementation is in charge of 0122 * this attribute, not the user. If the user changes the value of 0123 * the attribute (even if it ends up having the same value as the 0124 * default value) then the \c specified flag is 0125 * automatically flipped to \c true . To re-specify 0126 * the attribute as the default value from the DTD, the user must 0127 * delete the attribute. The implementation will then make a new 0128 * attribute available with \c specified set to 0129 * \c false and the default value (if one exists). 0130 * 0131 * In summary: 0132 * \li If the attribute has an assigned 0133 * value in the document then \c specified is 0134 * \c true , and the value is the assigned value. 0135 * 0136 * \li If the attribute has no assigned value in the 0137 * document and has a default value in the DTD, then 0138 * \c specified is \c false , and the value is 0139 * the default value in the DTD. 0140 * 0141 * \li If the attribute has no assigned value in the 0142 * document and has a value of #IMPLIED in the DTD, then the 0143 * attribute does not appear in the structure model of the 0144 * document. 0145 * 0146 * 0147 * 0148 */ 0149 bool specified() const; 0150 0151 /** 0152 * On retrieval, the value of the attribute is returned as a 0153 * string. Character and general entity references are replaced 0154 * with their values. 0155 * 0156 * On setting, this creates a \c Text node with the 0157 * unparsed contents of the string. 0158 * 0159 */ 0160 DOMString value() const; 0161 0162 /** 0163 * see value 0164 */ 0165 void setValue(const DOMString &); 0166 0167 /** 0168 * Introduced in DOM Level 2 0169 * 0170 * The Element node this attribute is attached to or null if this attribute 0171 * is not in use. 0172 */ 0173 Element ownerElement() const; 0174 0175 protected: 0176 0177 Attr(AttrImpl *_impl); 0178 }; 0179 0180 class NodeList; 0181 class Attr; 0182 class DOMString; 0183 0184 /** 0185 * By far the vast majority of objects (apart from text) that authors 0186 * encounter when traversing a document are \c Element 0187 * nodes. Assume the following XML document: <elementExample 0188 * id="demo"> <subelement1/> 0189 * <subelement2><subsubelement/></subelement2> 0190 * </elementExample> 0191 * 0192 * When represented using DOM, the top node is an \c Element 0193 * node for "elementExample", which contains two 0194 * child \c Element nodes, one for "subelement1" 0195 * and one for "subelement2". "subelement1" 0196 * contains no child nodes. 0197 * 0198 * Elements may have attributes associated with them; since the 0199 * \c Element interface inherits from \c Node 0200 * , the generic \c Node interface method 0201 * \c getAttributes may be used to retrieve the set of all 0202 * attributes for an element. There are methods on the \c Element 0203 * interface to retrieve either an \c Attr object 0204 * by name or an attribute value by name. In XML, where an attribute 0205 * value may contain entity references, an \c Attr object 0206 * should be retrieved to examine the possibly fairly complex sub-tree 0207 * representing the attribute value. On the other hand, in HTML, where 0208 * all attributes have simple string values, methods to directly 0209 * access an attribute value can safely be used as a convenience. 0210 * 0211 */ 0212 class KHTML_EXPORT Element : public Node 0213 { 0214 friend class Document; 0215 friend class DocumentFragment; 0216 friend class HTMLDocument; 0217 // friend class AttrImpl; 0218 friend class Attr; 0219 0220 public: 0221 Element(); 0222 Element(const Node &other) : Node() 0223 { 0224 (*this) = other; 0225 } 0226 Element(const Element &other); 0227 0228 Element &operator = (const Node &other); 0229 Element &operator = (const Element &other); 0230 0231 ~Element(); 0232 0233 /** 0234 * The name of the element. For example, in: <elementExample 0235 * id="demo"> ... </elementExample> , 0236 * \c tagName has the value \c "elementExample" 0237 * . Note that this is case-preserving in XML, as are all 0238 * of the operations of the DOM. The HTML DOM returns the 0239 * \c tagName of an HTML element in the canonical uppercase 0240 * form, regardless of the case in the source HTML document. 0241 * 0242 */ 0243 DOMString tagName() const; 0244 0245 /** 0246 * Retrieves an attribute value by name. 0247 * 0248 * @param name The name of the attribute to retrieve. 0249 * 0250 * @return The \c Attr value as a string, or the empty 0251 * string if that attribute does not have a specified or default 0252 * value. 0253 * 0254 */ 0255 DOMString getAttribute(const DOMString &name); 0256 0257 /** 0258 * Adds a new attribute. If an attribute with that name is already 0259 * present in the element, its value is changed to be that of the 0260 * value parameter. This value is a simple string, it is not 0261 * parsed as it is being set. So any markup (such as syntax to be 0262 * recognized as an entity reference) is treated as literal text, 0263 * and needs to be appropriately escaped by the implementation 0264 * when it is written out. In order to assign an attribute value 0265 * that contains entity references, the user must create an 0266 * \c Attr node plus any \c Text and 0267 * \c EntityReference nodes, build the appropriate subtree, 0268 * and use \c setAttributeNode to assign it as the 0269 * value of an attribute. 0270 * 0271 * @param name The name of the attribute to create or alter. 0272 * 0273 * @param value Value to set in string form. 0274 * 0275 * @return 0276 * 0277 * @exception DOMException 0278 * INVALID_CHARACTER_ERR: Raised if the specified name contains an 0279 * invalid character. 0280 * 0281 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0282 * 0283 */ 0284 void setAttribute(const DOMString &name, const DOMString &value); 0285 0286 /** 0287 * Removes an attribute by name. If the removed attribute has a 0288 * default value it is immediately replaced. 0289 * 0290 * @param name The name of the attribute to remove. 0291 * 0292 * @return 0293 * 0294 * @exception DOMException 0295 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0296 * 0297 */ 0298 void removeAttribute(const DOMString &name); 0299 0300 /** 0301 * Retrieves an \c Attr node by name. 0302 * 0303 * @param name The name of the attribute to retrieve. 0304 * 0305 * @return The \c Attr node with the specified 0306 * attribute name or \c null if there is no such 0307 * attribute. 0308 * 0309 */ 0310 Attr getAttributeNode(const DOMString &name); 0311 0312 /** 0313 * Adds a new attribute. If an attribute with that name is already 0314 * present in the element, it is replaced by the new one. 0315 * 0316 * @param newAttr The \c Attr node to add to the 0317 * attribute list. 0318 * 0319 * @return If the \c newAttr attribute replaces an 0320 * existing attribute with the same name, the previously existing 0321 * \c Attr node is returned, otherwise \c null 0322 * is returned. 0323 * 0324 * @exception DOMException 0325 * WRONG_DOCUMENT_ERR: Raised if \c newAttr was 0326 * created from a different document than the one that created the 0327 * element. 0328 * 0329 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0330 * 0331 * INUSE_ATTRIBUTE_ERR: Raised if \c newAttr is 0332 * already an attribute of another \c Element object. 0333 * The DOM user must explicitly clone \c Attr nodes to 0334 * re-use them in other elements. 0335 * 0336 */ 0337 Attr setAttributeNode(const Attr &newAttr); 0338 0339 /** 0340 * Removes the specified attribute. 0341 * 0342 * @param oldAttr The \c Attr node to remove from the 0343 * attribute list. If the removed \c Attr has a 0344 * default value it is immediately replaced. 0345 * 0346 * @return The \c Attr node that was removed. 0347 * 0348 * @exception DOMException 0349 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0350 * 0351 * NOT_FOUND_ERR: Raised if \c oldAttr is not an 0352 * attribute of the element. 0353 * 0354 */ 0355 Attr removeAttributeNode(const Attr &oldAttr); 0356 0357 /** 0358 * Returns a \c NodeList of all descendant elements 0359 * with a given tag name, in the order in which they would be 0360 * encountered in a preorder traversal of the \c Element 0361 * tree. 0362 * 0363 * @param name The name of the tag to match on. The special value 0364 * "*" matches all tags. 0365 * 0366 * @return A list of matching \c Element nodes. 0367 * 0368 */ 0369 NodeList getElementsByTagName(const DOMString &name); 0370 0371 /** 0372 * Introduced in DOM Level 2 0373 * Returns a NodeList of all the descendant Elements with a given local 0374 * name and namespace URI in the order in which they are encountered in a 0375 * preorder traversal of this Element tree. 0376 * 0377 * @param namespaceURI The namespace URI of the elements to match on. The 0378 * special value "*" matches all namespaces. 0379 * 0380 * @param localName The local name of the elements to match on. The special 0381 * value "*" matches all local names. 0382 * 0383 * @return A new NodeList object containing all the matched Elements. 0384 */ 0385 NodeList getElementsByTagNameNS(const DOMString &namespaceURI, 0386 const DOMString &localName); 0387 0388 /** 0389 * Introduced in HTML 5. 0390 * No Exceptions. 0391 * 0392 * Returns a \c NodeList of all the \c Element 's 0393 * with a given class name in the order in which they 0394 * would be encountered in a preorder traversal of the 0395 * \c Document tree. 0396 * 0397 * @param tagname An unordered set of unique space-separated 0398 * tokens representing classes. 0399 * 0400 * @return A new \c NodeList object containing all the 0401 * matched \c Element s. 0402 * 0403 * @since 4.1 0404 */ 0405 NodeList getElementsByClassName(const DOMString &className); 0406 0407 /** 0408 * Introduced in DOM Level 2. 0409 * 0410 * No Exceptions. 0411 * 0412 * Retrieves an attribute value by local name and namespace URI. HTML-only 0413 * DOM implementations do not need to implement this method. 0414 * 0415 * @param namespaceURI The namespace URI of the attribute to retrieve. 0416 * 0417 * @param localName The local name of the attribute to retrieve. 0418 * 0419 * @return The Attr value as a string, or the empty string if that 0420 * attribute does not have a specified or default value. 0421 */ 0422 DOMString getAttributeNS(const DOMString &namespaceURI, 0423 const DOMString &localName); 0424 0425 /** 0426 * Introduced in DOM Level 2 0427 * 0428 * Adds a new attribute. If an attribute with the same local name and 0429 * namespace URI is already present on the element, its prefix is changed 0430 * to be the prefix part of the qualifiedName, and its value is changed to 0431 * be the value parameter. This value is a simple string; it is not parsed 0432 * as it is being set. So any markup (such as syntax to be recognized as an 0433 * entity reference) is treated as literal text, and needs to be 0434 * appropriately escaped by the implementation when it is written out. In 0435 * order to assign an attribute value that contains entity references, the 0436 * user must create an Attr node plus any Text and EntityReference nodes, 0437 * build the appropriate subtree, and use setAttributeNodeNS or 0438 * setAttributeNode to assign it as the value of an attribute. 0439 * 0440 * HTML-only DOM implementations do not need to implement this method. 0441 * 0442 * @param namespaceURI The namespace URI of the attribute to create or 0443 * alter. 0444 * 0445 * @param qualifiedName The qualified name of the attribute to create or 0446 * alter. 0447 * 0448 * @param value The value to set in string form. 0449 * 0450 * @exception DOMException 0451 * INVALID_CHARACTER_ERR: Raised if the specified qualified name contains 0452 * an illegal character. 0453 * 0454 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0455 * 0456 * NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the 0457 * qualifiedName has a prefix and the namespaceURI is null, if the 0458 * qualifiedName has a prefix that is "xml" and the namespaceURI is 0459 * different from "http://www.w3.org/XML/1998/namespace", or if the 0460 * qualifiedName is "xmlns" and the namespaceURI is different from 0461 * "http://www.w3.org/2000/xmlns/". 0462 */ 0463 void setAttributeNS(const DOMString &namespaceURI, 0464 const DOMString &qualifiedName, 0465 const DOMString &value); 0466 0467 /** 0468 * Introduced in DOM Level 2 0469 * 0470 * Removes an attribute by local name and namespace URI. If the removed 0471 * attribute has a default value it is immediately replaced. The replacing 0472 * attribute has the same namespace URI and local name, as well as the 0473 * original prefix. 0474 * 0475 * HTML-only DOM implementations do not need to implement this method. 0476 * 0477 * @param namespaceURI The namespace URI of the attribute to remove. 0478 * 0479 * @param localName The local name of the attribute to remove. 0480 * 0481 * @exception DOMException 0482 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0483 */ 0484 void removeAttributeNS(const DOMString &namespaceURI, 0485 const DOMString &localName); 0486 0487 /** 0488 * Introduced in DOM Level 2 0489 * 0490 * Retrieves an Attr node by local name and namespace URI. HTML-only DOM 0491 * implementations do not need to implement this method. 0492 * 0493 * @param namespaceURI The namespace URI of the attribute to retrieve. 0494 * 0495 * @param localName The local name of the attribute to retrieve. 0496 * 0497 * @return The Attr node with the specified attribute local name and 0498 * namespace URI or null if there is no such attribute. 0499 */ 0500 Attr getAttributeNodeNS(const DOMString &namespaceURI, 0501 const DOMString &localName); 0502 0503 /** 0504 * Introduced in DOM Level 2 0505 * 0506 * Adds a new attribute. If an attribute with that local name and that 0507 * namespace URI is already present in the element, it is replaced by the 0508 * new one. 0509 * 0510 * HTML-only DOM implementations do not need to implement this method. 0511 * 0512 * @param newAttr The Attr node to add to the attribute list. 0513 * 0514 * @return If the newAttr attribute replaces an existing attribute with the 0515 * same local name and namespace URI, the replaced Attr node is returned, 0516 * otherwise null is returned. 0517 * 0518 * @exception DOMException 0519 * WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different 0520 * document than the one that created the element. 0521 * 0522 * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly. 0523 * 0524 * INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of 0525 * another Element object. The DOM user must explicitly clone Attr nodes to 0526 * re-use them in other elements. 0527 */ 0528 Attr setAttributeNodeNS(const Attr &newAttr); 0529 0530 /** 0531 * Returns true when an attribute with a given name is specified on this 0532 * element or has a default value, false otherwise. 0533 * Introduced in DOM Level 2. 0534 * 0535 * @param name The name of the attribute to look for. 0536 * 0537 * @return true if an attribute with the given name is specified on this 0538 * element or has a default value, false otherwise. 0539 */ 0540 bool hasAttribute(const DOMString &name); 0541 0542 /** 0543 * Introduced in DOM Level 2 0544 * 0545 * Returns true when an attribute with a given local name and namespace URI 0546 * is specified on this element or has a default value, false otherwise. 0547 * HTML-only DOM implementations do not need to implement this method. 0548 * 0549 * @param namespaceURI The namespace URI of the attribute to look for. 0550 * 0551 * @param localName The local name of the attribute to look for. 0552 * 0553 * @return true if an attribute with the given local name and namespace URI 0554 * is specified or has a default value on this element, false otherwise. 0555 */ 0556 bool hasAttributeNS(const DOMString &namespaceURI, 0557 const DOMString &localName); 0558 0559 /** 0560 * Introduced in DOM Level 2 0561 * This method is from the CSSStyleDeclaration interface 0562 * 0563 * The style attribute 0564 */ 0565 CSSStyleDeclaration style(); 0566 0567 /** 0568 * Introduced in DOM level 3 0569 * This method is part of the ElementTraversal interface 0570 * 0571 * The first child node which is of nodeType ELEMENT_NODE. 0572 * 0573 */ 0574 Element firstElementChild() const; 0575 0576 /** 0577 * Introduced in DOM level 3 0578 * This method is part of the ElementTraversal interface 0579 * 0580 * @return The last child node of that element which is of nodeType ELEMENT_NODE. 0581 * 0582 */ 0583 Element lastElementChild() const; 0584 0585 /** 0586 * Introduced in DOM level 3 0587 * This method is part of the ElementTraversal interface 0588 * 0589 * @return The sibling node of that element which most immediately precedes that element in document order, 0590 * and which is of nodeType ELEMENT_NODE 0591 * 0592 */ 0593 Element previousElementSibling() const; 0594 0595 /** 0596 * Introduced in DOM level 3 0597 * This method is part of the ElementTraversal interface 0598 * 0599 * @return The sibling node of that element which most immediately follows that element in document order, 0600 * and which is of nodeType ELEMENT_NODE 0601 * 0602 */ 0603 Element nextElementSibling() const; 0604 0605 /** 0606 * Introduced in DOM level 3 0607 * This method is part of the ElementTraversal interface 0608 * 0609 * @return The current number of child nodes of that element which are of nodeType ELEMENT_NODE 0610 * 0611 */ 0612 unsigned long childElementCount() const; 0613 0614 /** 0615 * Introduced in Selectors Level 1. 0616 * 0617 * Returns the first (in document order) element in this element's subtree 0618 * matching the given CSS selector @p query. 0619 * 0620 * @since 4.5 0621 */ 0622 Element querySelector(const DOMString &query) const; 0623 0624 /** 0625 * Introduced in Selectors Level 1. 0626 * 0627 * Returns all (in document order) elements in this element's subtree 0628 * matching the given CSS selector @p query. Note that the returned NodeList 0629 * is static and not live, and will not be updated when the document 0630 * changes 0631 * 0632 * @since 4.5 0633 */ 0634 NodeList querySelectorAll(const DOMString &query) const; 0635 0636 /** 0637 * not part of the official DOM 0638 * 0639 * This method will always reflect the editability setting of this 0640 * element as specified by a direct or indirect (that means, inherited) 0641 * assignment to contentEditable or the respective CSS rule, even if 0642 * design mode is active. 0643 * 0644 * @return whether this element is editable. 0645 * @see setContentEditable 0646 */ 0647 bool contentEditable() const; 0648 0649 /** 0650 * not part of the official DOM 0651 * 0652 * This element can be made editable by setting its contentEditable 0653 * property to @p true. The setting will be inherited to its children 0654 * as well. 0655 * 0656 * Setting or clearing contentEditable when design mode is active will 0657 * take no effect. However, its status will still be propagated to all 0658 * child elements. 0659 * 0660 * @param enabled @p true to make this element editable, @p false 0661 * otherwise. 0662 * @see DOM::Document::designMode 0663 */ 0664 void setContentEditable(bool enabled); 0665 0666 /** 0667 * @internal 0668 * not part of the DOM 0669 */ 0670 bool isHTMLElement() const; 0671 0672 /** 0673 * KHTML extension to DOM 0674 * This method returns the associated form element. 0675 * returns null if this element is not a form-like element 0676 * or if this elment is not in the scope of a form element. 0677 */ 0678 Element form() const; 0679 0680 static bool khtmlValidAttrName(const DOMString &name); 0681 static bool khtmlValidPrefix(const DOMString &name); 0682 static bool khtmlValidQualifiedName(const DOMString &name); 0683 0684 static bool khtmlMalformedQualifiedName(const DOMString &name); 0685 static bool khtmlMalformedPrefix(const DOMString &name); 0686 protected: 0687 Element(ElementImpl *_impl); 0688 }; 0689 0690 } //namespace 0691 #endif