1 | // |
2 | // Element.h |
3 | // |
4 | // Library: XML |
5 | // Package: DOM |
6 | // Module: DOM |
7 | // |
8 | // Definition of the DOM Element class. |
9 | // |
10 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
11 | // and Contributors. |
12 | // |
13 | // SPDX-License-Identifier: BSL-1.0 |
14 | // |
15 | |
16 | |
17 | #ifndef DOM_Element_INCLUDED |
18 | #define DOM_Element_INCLUDED |
19 | |
20 | |
21 | #include "Poco/XML/XML.h" |
22 | #include "Poco/DOM/AbstractContainerNode.h" |
23 | #include "Poco/XML/Name.h" |
24 | |
25 | |
26 | namespace Poco { |
27 | namespace XML { |
28 | |
29 | |
30 | class Attr; |
31 | class NodeList; |
32 | class Document; |
33 | |
34 | |
35 | class XML_API Element: public AbstractContainerNode |
36 | /// The Element interface represents an element in an XML document. |
37 | /// Elements may have attributes associated with them; since the Element interface |
38 | /// inherits from Node, the generic Node interface attribute attributes may |
39 | /// be used to retrieve the set of all attributes for an element. There are |
40 | /// methods on the Element interface to retrieve either an Attr object by name |
41 | /// or an attribute value by name. In XML, where an attribute value may contain |
42 | /// entity references, an Attr object should be retrieved to examine the possibly |
43 | /// fairly complex sub-tree representing the attribute value. |
44 | { |
45 | public: |
46 | const XMLString& tagName() const; |
47 | /// Returns the name of the element. |
48 | /// |
49 | /// For example, in |
50 | /// |
51 | /// <elementExample id="demo"> |
52 | /// ... |
53 | /// </elementExample> |
54 | /// |
55 | /// tagName has the value "elementExample". Note that this is case-preserving in XML, |
56 | /// as are all of the operations of the DOM. |
57 | |
58 | const XMLString& getAttribute(const XMLString& name) const; |
59 | /// Retrieves an attribute value by name. |
60 | /// |
61 | /// Returns the attribute's value, if the attribute |
62 | /// exists, or an empty string otherwise. |
63 | |
64 | void setAttribute(const XMLString& name, const XMLString& value); |
65 | /// Adds a new attribute. If an attribute with that name is already present |
66 | /// in the element, its value is changed to be that of the value parameter. |
67 | /// This value is a simple string; it is not parsed as it is being set. So any |
68 | /// markup (such as syntax to be recognized as an entity reference) is treated |
69 | /// as literal text, and needs to be appropriately escaped by the implementation |
70 | /// when it is written out. |
71 | |
72 | void removeAttribute(const XMLString& name); |
73 | /// Removes an attribute by name. |
74 | |
75 | Attr* getAttributeNode(const XMLString& name) const; |
76 | /// Retrieves an Attr node by name. |
77 | |
78 | Attr* setAttributeNode(Attr* newAttr); |
79 | /// Adds a new attribute. If an attribute with that name is already |
80 | /// present in the element, it is replaced by the new one. |
81 | |
82 | Attr* addAttributeNodeNP(Attr* oldAttr, Attr* newAttr); |
83 | /// For internal use only. |
84 | /// Adds a new attribute after oldAttr. |
85 | /// If oldAttr is 0, newAttr is set as first attribute. |
86 | /// Returns newAttr. |
87 | /// Does not fire any events. |
88 | |
89 | Attr* removeAttributeNode(Attr* oldAttr); |
90 | /// Removes the specified attribute. |
91 | |
92 | NodeList* getElementsByTagName(const XMLString& name) const; |
93 | /// Returns a NodeList of all descendant elements with a given tag |
94 | /// name, in the order in which they would be encountered in a |
95 | /// preorder traversal of the Element tree. |
96 | /// |
97 | /// The special name "*" matches all tags. |
98 | /// |
99 | /// The returned NodeList must be released with a call |
100 | /// to release() when no longer needed. |
101 | |
102 | void normalize(); |
103 | /// Puts all Text nodes in the full depth of the sub-tree underneath this Element, |
104 | /// including attribute nodes, into a "normal" form where only markup (e.g., |
105 | /// tags, comments, processing instructions, CDATA sections, and entity references) |
106 | /// separates Text nodes, i.e., there are no adjacent Text nodes. This can be |
107 | /// used to ensure that the DOM view of a document is the same as if it were |
108 | /// saved and re-loaded, and is useful when operations (such as XPointer |
109 | /// lookups) that depend on a particular document tree structure are to be used. |
110 | /// |
111 | /// Note: In cases where the document contains CDATASections, the normalize |
112 | /// operation alone may not be sufficient, since XPointers do not differentiate |
113 | /// between Text nodes and CDATASection nodes. |
114 | |
115 | // DOM Level 2 |
116 | const XMLString& getAttributeNS(const XMLString& namespaceURI, const XMLString& localName) const; |
117 | /// Retrieves an attribute value by name. |
118 | /// |
119 | /// Returns the attribute's value, if the attribute |
120 | /// exists, or an empty string otherwise. |
121 | |
122 | void setAttributeNS(const XMLString& namespaceURI, const XMLString& qualifiedName, const XMLString& value); |
123 | /// Adds a new attribute. If an attribute with that name |
124 | /// is already present in the element, its value is changed |
125 | /// to be that of the value parameter. |
126 | |
127 | void removeAttributeNS(const XMLString& namespaceURI, const XMLString& localName); |
128 | /// Removes an attribute by name. |
129 | |
130 | Attr* getAttributeNodeNS(const XMLString& namespaceURI, const XMLString& localName) const; |
131 | /// Retrieves an Attr node by name. |
132 | |
133 | Attr* setAttributeNodeNS(Attr* newAttr); |
134 | /// Adds a new attribute. If an attribute with that name is already |
135 | /// present in the element, it is replaced by the new one. |
136 | |
137 | bool hasAttribute(const XMLString& name) const; |
138 | /// Returns true if and only if the element has the specified attribute. |
139 | |
140 | bool hasAttributeNS(const XMLString& namespaceURI, const XMLString& localName) const; |
141 | /// Returns true if and only if the element has the specified attribute. |
142 | |
143 | NodeList* getElementsByTagNameNS(const XMLString& namespaceURI, const XMLString& localName) const; |
144 | /// Returns a NodeList of all the descendant Elements with a given local name and namespace URI |
145 | /// in the order in which they are encountered in a preorder traversal of this Element tree. |
146 | /// |
147 | /// The special value "*" matches all namespaces, or local names respectively. |
148 | /// |
149 | /// The returned NodeList must be released with a call |
150 | /// to release() when no longer needed. |
151 | |
152 | const XMLString& namespaceURI() const; |
153 | XMLString prefix() const; |
154 | const XMLString& localName() const; |
155 | bool hasAttributes() const; |
156 | XMLString innerText() const; |
157 | |
158 | Element* getChildElement(const XMLString& name) const; |
159 | /// Returns the first child element with the given name, or null |
160 | /// if such an element does not exist. |
161 | /// |
162 | /// This method is an extension to the W3C Document Object Model. |
163 | |
164 | Element* getChildElementNS(const XMLString& namespaceURI, const XMLString& localName) const; |
165 | /// Returns the first child element with the given namespaceURI and localName, |
166 | /// or null if such an element does not exist. |
167 | /// |
168 | /// This method is an extension to the W3C Document Object Model. |
169 | |
170 | Element* getElementById(const XMLString& elementId, const XMLString& idAttribute) const; |
171 | /// Returns the first Element whose ID attribute (given in idAttribute) |
172 | /// has the given elementId. If no such element exists, returns null. |
173 | /// |
174 | /// This method is an extension to the W3C Document Object Model. |
175 | |
176 | Element* getElementByIdNS(const XMLString& elementId, const XMLString& idAttributeURI, const XMLString& idAttributeLocalName) const; |
177 | /// Returns the first Element whose ID attribute (given in idAttributeURI and idAttributeLocalName) |
178 | /// has the given elementId. If no such element exists, returns null. |
179 | /// |
180 | /// This method is an extension to the W3C Document Object Model. |
181 | |
182 | // Node |
183 | const XMLString& nodeName() const; |
184 | NamedNodeMap* attributes() const; |
185 | unsigned short nodeType() const; |
186 | |
187 | protected: |
188 | Element(Document* pOwnerDocument, const XMLString& namespaceURI, const XMLString& localName, const XMLString& qname); |
189 | Element(Document* pOwnerDocument, const Element& elem); |
190 | ~Element(); |
191 | |
192 | Node* copyNode(bool deep, Document* pOwnerDocument) const; |
193 | |
194 | void dispatchNodeRemovedFromDocument(); |
195 | void dispatchNodeInsertedIntoDocument(); |
196 | |
197 | private: |
198 | const Name& _name; |
199 | Attr* _pFirstAttr; |
200 | |
201 | friend class Attr; |
202 | friend class Document; |
203 | friend class AttrMap; |
204 | }; |
205 | |
206 | |
207 | // |
208 | // inlines |
209 | // |
210 | inline const XMLString& Element::tagName() const |
211 | { |
212 | return _name.qname(); |
213 | } |
214 | |
215 | |
216 | } } // namespace Poco::XML |
217 | |
218 | |
219 | #endif // DOM_Element_INCLUDED |
220 | |