Various documentation fixes ported from 4.8
[profile/ivi/qtbase.git] / src / xml / dom / qdom.h
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
5 **
6 ** This file is part of the QtXml module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
16 **
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
20 **
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
28 **
29 ** Other Usage
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
32 **
33 **
34 **
35 **
36 **
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #ifndef QDOM_H
43 #define QDOM_H
44
45 #include <QtCore/qstring.h>
46
47 QT_BEGIN_HEADER
48
49 QT_BEGIN_NAMESPACE
50
51
52 #ifndef QT_NO_DOM
53
54 class QIODevice;
55 class QTextStream;
56
57 class QXmlInputSource;
58 class QXmlReader;
59
60 class QDomDocumentPrivate;
61 class QDomDocumentTypePrivate;
62 class QDomDocumentFragmentPrivate;
63 class QDomNodePrivate;
64 class QDomNodeListPrivate;
65 class QDomImplementationPrivate;
66 class QDomElementPrivate;
67 class QDomNotationPrivate;
68 class QDomEntityPrivate;
69 class QDomEntityReferencePrivate;
70 class QDomProcessingInstructionPrivate;
71 class QDomAttrPrivate;
72 class QDomCharacterDataPrivate;
73 class QDomTextPrivate;
74 class QDomCommentPrivate;
75 class QDomCDATASectionPrivate;
76 class QDomNamedNodeMapPrivate;
77 class QDomImplementationPrivate;
78
79 class QDomNodeList;
80 class QDomElement;
81 class QDomText;
82 class QDomComment;
83 class QDomCDATASection;
84 class QDomProcessingInstruction;
85 class QDomAttr;
86 class QDomEntityReference;
87 class QDomDocument;
88 class QDomNamedNodeMap;
89 class QDomDocument;
90 class QDomDocumentFragment;
91 class QDomDocumentType;
92 class QDomImplementation;
93 class QDomNode;
94 class QDomEntity;
95 class QDomNotation;
96 class QDomCharacterData;
97
98 class Q_XML_EXPORT QDomImplementation
99 {
100 public:
101     QDomImplementation();
102     QDomImplementation(const QDomImplementation&);
103     ~QDomImplementation();
104     QDomImplementation& operator= (const QDomImplementation&);
105     bool operator== (const QDomImplementation&) const;
106     bool operator!= (const QDomImplementation&) const;
107
108     // functions
109     bool hasFeature(const QString& feature, const QString& version) const;
110     QDomDocumentType createDocumentType(const QString& qName, const QString& publicId, const QString& systemId);
111     QDomDocument createDocument(const QString& nsURI, const QString& qName, const QDomDocumentType& doctype);
112
113     enum InvalidDataPolicy { AcceptInvalidChars = 0, DropInvalidChars, ReturnNullNode };
114     static InvalidDataPolicy invalidDataPolicy();
115     static void setInvalidDataPolicy(InvalidDataPolicy policy);
116
117     // Qt extension
118     bool isNull();
119
120 private:
121     QDomImplementationPrivate* impl;
122     QDomImplementation(QDomImplementationPrivate*);
123
124     friend class QDomDocument;
125 };
126
127 class Q_XML_EXPORT QDomNode
128 {
129 public:
130     enum NodeType {
131         ElementNode               = 1,
132         AttributeNode             = 2,
133         TextNode                  = 3,
134         CDATASectionNode          = 4,
135         EntityReferenceNode       = 5,
136         EntityNode                = 6,
137         ProcessingInstructionNode = 7,
138         CommentNode               = 8,
139         DocumentNode              = 9,
140         DocumentTypeNode          = 10,
141         DocumentFragmentNode      = 11,
142         NotationNode              = 12,
143         BaseNode                  = 21,// this is not in the standard
144         CharacterDataNode         = 22 // this is not in the standard
145     };
146
147     enum EncodingPolicy
148     {
149         EncodingFromDocument      = 1,
150         EncodingFromTextStream    = 2
151     };
152
153     QDomNode();
154     QDomNode(const QDomNode&);
155     QDomNode& operator= (const QDomNode&);
156     bool operator== (const QDomNode&) const;
157     bool operator!= (const QDomNode&) const;
158     ~QDomNode();
159
160     // DOM functions
161     QDomNode insertBefore(const QDomNode& newChild, const QDomNode& refChild);
162     QDomNode insertAfter(const QDomNode& newChild, const QDomNode& refChild);
163     QDomNode replaceChild(const QDomNode& newChild, const QDomNode& oldChild);
164     QDomNode removeChild(const QDomNode& oldChild);
165     QDomNode appendChild(const QDomNode& newChild);
166     bool hasChildNodes() const;
167     QDomNode cloneNode(bool deep = true) const;
168     void normalize();
169     bool isSupported(const QString& feature, const QString& version) const;
170
171     // DOM read-only attributes
172     QString nodeName() const;
173     NodeType nodeType() const;
174     QDomNode parentNode() const;
175     QDomNodeList childNodes() const;
176     QDomNode firstChild() const;
177     QDomNode lastChild() const;
178     QDomNode previousSibling() const;
179     QDomNode nextSibling() const;
180     QDomNamedNodeMap attributes() const;
181     QDomDocument ownerDocument() const;
182     QString namespaceURI() const;
183     QString localName() const;
184     bool hasAttributes() const;
185
186     // DOM attributes
187     QString nodeValue() const;
188     void setNodeValue(const QString&);
189     QString prefix() const;
190     void setPrefix(const QString& pre);
191
192     // Qt extensions
193     bool isAttr() const;
194     bool isCDATASection() const;
195     bool isDocumentFragment() const;
196     bool isDocument() const;
197     bool isDocumentType() const;
198     bool isElement() const;
199     bool isEntityReference() const;
200     bool isText() const;
201     bool isEntity() const;
202     bool isNotation() const;
203     bool isProcessingInstruction() const;
204     bool isCharacterData() const;
205     bool isComment() const;
206
207     /**
208      * Shortcut to avoid dealing with QDomNodeList
209      * all the time.
210      */
211     QDomNode namedItem(const QString& name) const;
212
213     bool isNull() const;
214     void clear();
215
216     QDomAttr toAttr() const;
217     QDomCDATASection toCDATASection() const;
218     QDomDocumentFragment toDocumentFragment() const;
219     QDomDocument toDocument() const;
220     QDomDocumentType toDocumentType() const;
221     QDomElement toElement() const;
222     QDomEntityReference toEntityReference() const;
223     QDomText toText() const;
224     QDomEntity toEntity() const;
225     QDomNotation toNotation() const;
226     QDomProcessingInstruction toProcessingInstruction() const;
227     QDomCharacterData toCharacterData() const;
228     QDomComment toComment() const;
229
230     void save(QTextStream&, int) const;
231     void save(QTextStream&, int, EncodingPolicy) const; // ### Qt 5: Merge overload(if we at all keep this)
232
233     QDomElement firstChildElement(const QString &tagName = QString()) const;
234     QDomElement lastChildElement(const QString &tagName = QString()) const;
235     QDomElement previousSiblingElement(const QString &tagName = QString()) const;
236     QDomElement nextSiblingElement(const QString &taName = QString()) const;
237
238     int lineNumber() const;
239     int columnNumber() const;
240
241 protected:
242     QDomNodePrivate* impl;
243     QDomNode(QDomNodePrivate*);
244
245 private:
246     friend class QDomDocument;
247     friend class QDomDocumentType;
248     friend class QDomNodeList;
249     friend class QDomNamedNodeMap;
250 };
251
252 class Q_XML_EXPORT QDomNodeList
253 {
254 public:
255     QDomNodeList();
256     QDomNodeList(const QDomNodeList&);
257     QDomNodeList& operator= (const QDomNodeList&);
258     bool operator== (const QDomNodeList&) const;
259     bool operator!= (const QDomNodeList&) const;
260     ~QDomNodeList();
261
262     // DOM functions
263     QDomNode item(int index) const;
264     inline QDomNode at(int index) const { return item(index); } // Qt API consistency
265
266     // DOM read only attributes
267     uint length() const;
268     inline int count() const { return length(); } // Qt API consitancy
269     inline int size() const { return length(); } // Qt API consistency
270     inline bool isEmpty() const { return length() == 0; } // Qt API consistency
271
272 private:
273     QDomNodeListPrivate* impl;
274     QDomNodeList(QDomNodeListPrivate*);
275
276     friend class QDomNode;
277     friend class QDomElement;
278     friend class QDomDocument;
279 };
280
281 class Q_XML_EXPORT QDomDocumentType : public QDomNode
282 {
283 public:
284     QDomDocumentType();
285     QDomDocumentType(const QDomDocumentType& x);
286     QDomDocumentType& operator= (const QDomDocumentType&);
287
288     // DOM read only attributes
289     QString name() const;
290     QDomNamedNodeMap entities() const;
291     QDomNamedNodeMap notations() const;
292     QString publicId() const;
293     QString systemId() const;
294     QString internalSubset() const;
295
296     // Overridden from QDomNode
297     inline QDomNode::NodeType nodeType() const { return DocumentTypeNode; }
298
299 private:
300     QDomDocumentType(QDomDocumentTypePrivate*);
301
302     friend class QDomImplementation;
303     friend class QDomDocument;
304     friend class QDomNode;
305 };
306
307 class Q_XML_EXPORT QDomDocument : public QDomNode
308 {
309 public:
310     QDomDocument();
311     explicit QDomDocument(const QString& name);
312     explicit QDomDocument(const QDomDocumentType& doctype);
313     QDomDocument(const QDomDocument& x);
314     QDomDocument& operator= (const QDomDocument&);
315     ~QDomDocument();
316
317     // DOM functions
318     QDomElement createElement(const QString& tagName);
319     QDomDocumentFragment createDocumentFragment();
320     QDomText createTextNode(const QString& data);
321     QDomComment createComment(const QString& data);
322     QDomCDATASection createCDATASection(const QString& data);
323     QDomProcessingInstruction createProcessingInstruction(const QString& target, const QString& data);
324     QDomAttr createAttribute(const QString& name);
325     QDomEntityReference createEntityReference(const QString& name);
326     QDomNodeList elementsByTagName(const QString& tagname) const;
327     QDomNode importNode(const QDomNode& importedNode, bool deep);
328     QDomElement createElementNS(const QString& nsURI, const QString& qName);
329     QDomAttr createAttributeNS(const QString& nsURI, const QString& qName);
330     QDomNodeList elementsByTagNameNS(const QString& nsURI, const QString& localName);
331     QDomElement elementById(const QString& elementId);
332
333     // DOM read only attributes
334     QDomDocumentType doctype() const;
335     QDomImplementation implementation() const;
336     QDomElement documentElement() const;
337
338     // Overridden from QDomNode
339     inline QDomNode::NodeType nodeType() const { return DocumentNode; }
340
341     // Qt extensions
342     bool setContent(const QByteArray& text, bool namespaceProcessing, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
343     bool setContent(const QString& text, bool namespaceProcessing, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
344     bool setContent(QIODevice* dev, bool namespaceProcessing, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
345     bool setContent(QXmlInputSource *source, bool namespaceProcessing, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
346     bool setContent(const QByteArray& text, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
347     bool setContent(const QString& text, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
348     bool setContent(QIODevice* dev, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
349     bool setContent(QXmlInputSource *source, QXmlReader *reader, QString *errorMsg=0, int *errorLine=0, int *errorColumn=0 );
350
351     // Qt extensions
352     QString toString(int = 1) const;
353     QByteArray toByteArray(int = 1) const;
354
355 private:
356     QDomDocument(QDomDocumentPrivate*);
357
358     friend class QDomNode;
359 };
360
361 class Q_XML_EXPORT QDomNamedNodeMap
362 {
363 public:
364     QDomNamedNodeMap();
365     QDomNamedNodeMap(const QDomNamedNodeMap&);
366     QDomNamedNodeMap& operator= (const QDomNamedNodeMap&);
367     bool operator== (const QDomNamedNodeMap&) const;
368     bool operator!= (const QDomNamedNodeMap&) const;
369     ~QDomNamedNodeMap();
370
371     // DOM functions
372     QDomNode namedItem(const QString& name) const;
373     QDomNode setNamedItem(const QDomNode& newNode);
374     QDomNode removeNamedItem(const QString& name);
375     QDomNode item(int index) const;
376     QDomNode namedItemNS(const QString& nsURI, const QString& localName) const;
377     QDomNode setNamedItemNS(const QDomNode& newNode);
378     QDomNode removeNamedItemNS(const QString& nsURI, const QString& localName);
379
380     // DOM read only attributes
381     uint length() const;
382     int count() const { return length(); } // Qt API consitancy
383     inline int size() const { return length(); } // Qt API consistency
384     inline bool isEmpty() const { return length() == 0; } // Qt API consistency
385
386     // Qt extension
387     bool contains(const QString& name) const;
388
389 private:
390     QDomNamedNodeMapPrivate* impl;
391     QDomNamedNodeMap(QDomNamedNodeMapPrivate*);
392
393     friend class QDomNode;
394     friend class QDomDocumentType;
395     friend class QDomElement;
396 };
397
398 class Q_XML_EXPORT QDomDocumentFragment : public QDomNode
399 {
400 public:
401     QDomDocumentFragment();
402     QDomDocumentFragment(const QDomDocumentFragment& x);
403     QDomDocumentFragment& operator= (const QDomDocumentFragment&);
404
405     // Overridden from QDomNode
406     inline QDomNode::NodeType nodeType() const { return DocumentFragmentNode; }
407
408 private:
409     QDomDocumentFragment(QDomDocumentFragmentPrivate*);
410
411     friend class QDomDocument;
412     friend class QDomNode;
413 };
414
415 class Q_XML_EXPORT QDomCharacterData : public QDomNode
416 {
417 public:
418     QDomCharacterData();
419     QDomCharacterData(const QDomCharacterData& x);
420     QDomCharacterData& operator= (const QDomCharacterData&);
421
422     // DOM functions
423     QString substringData(unsigned long offset, unsigned long count);
424     void appendData(const QString& arg);
425     void insertData(unsigned long offset, const QString& arg);
426     void deleteData(unsigned long offset, unsigned long count);
427     void replaceData(unsigned long offset, unsigned long count, const QString& arg);
428
429     // DOM read only attributes
430     uint length() const;
431
432     // DOM attributes
433     QString data() const;
434     void setData(const QString&);
435
436     // Overridden from QDomNode
437     QDomNode::NodeType nodeType() const;
438
439 private:
440     QDomCharacterData(QDomCharacterDataPrivate*);
441
442     friend class QDomDocument;
443     friend class QDomText;
444     friend class QDomComment;
445     friend class QDomNode;
446 };
447
448 class Q_XML_EXPORT QDomAttr : public QDomNode
449 {
450 public:
451     QDomAttr();
452     QDomAttr(const QDomAttr& x);
453     QDomAttr& operator= (const QDomAttr&);
454
455     // DOM read only attributes
456     QString name() const;
457     bool specified() const;
458     QDomElement ownerElement() const;
459
460     // DOM attributes
461     QString value() const;
462     void setValue(const QString&);
463
464     // Overridden from QDomNode
465     inline QDomNode::NodeType nodeType() const { return AttributeNode; }
466
467 private:
468     QDomAttr(QDomAttrPrivate*);
469
470     friend class QDomDocument;
471     friend class QDomElement;
472     friend class QDomNode;
473 };
474
475 class Q_XML_EXPORT QDomElement : public QDomNode
476 {
477 public:
478     QDomElement();
479     QDomElement(const QDomElement& x);
480     QDomElement& operator= (const QDomElement&);
481
482     // DOM functions
483     QString attribute(const QString& name, const QString& defValue = QString() ) const;
484     void setAttribute(const QString& name, const QString& value);
485     void setAttribute(const QString& name, qlonglong value);
486     void setAttribute(const QString& name, qulonglong value);
487     inline void setAttribute(const QString& name, int value)
488         { setAttribute(name, qlonglong(value)); }
489     inline void setAttribute(const QString& name, uint value)
490         { setAttribute(name, qulonglong(value)); }
491     void setAttribute(const QString& name, float value);
492     void setAttribute(const QString& name, double value);
493     void removeAttribute(const QString& name);
494     QDomAttr attributeNode(const QString& name);
495     QDomAttr setAttributeNode(const QDomAttr& newAttr);
496     QDomAttr removeAttributeNode(const QDomAttr& oldAttr);
497     QDomNodeList elementsByTagName(const QString& tagname) const;
498     bool hasAttribute(const QString& name) const;
499
500     QString attributeNS(const QString nsURI, const QString& localName, const QString& defValue = QString()) const;
501     void setAttributeNS(const QString nsURI, const QString& qName, const QString& value);
502     inline void setAttributeNS(const QString nsURI, const QString& qName, int value)
503         { setAttributeNS(nsURI, qName, qlonglong(value)); }
504     inline void setAttributeNS(const QString nsURI, const QString& qName, uint value)
505         { setAttributeNS(nsURI, qName, qulonglong(value)); }
506     void setAttributeNS(const QString nsURI, const QString& qName, qlonglong value);
507     void setAttributeNS(const QString nsURI, const QString& qName, qulonglong value);
508     void setAttributeNS(const QString nsURI, const QString& qName, double value);
509     void removeAttributeNS(const QString& nsURI, const QString& localName);
510     QDomAttr attributeNodeNS(const QString& nsURI, const QString& localName);
511     QDomAttr setAttributeNodeNS(const QDomAttr& newAttr);
512     QDomNodeList elementsByTagNameNS(const QString& nsURI, const QString& localName) const;
513     bool hasAttributeNS(const QString& nsURI, const QString& localName) const;
514
515     // DOM read only attributes
516     QString tagName() const;
517     void setTagName(const QString& name); // Qt extension
518
519     // Overridden from QDomNode
520     QDomNamedNodeMap attributes() const;
521     inline QDomNode::NodeType nodeType() const { return ElementNode; }
522
523     QString text() const;
524
525 private:
526     QDomElement(QDomElementPrivate*);
527
528     friend class QDomDocument;
529     friend class QDomNode;
530     friend class QDomAttr;
531 };
532
533 class Q_XML_EXPORT QDomText : public QDomCharacterData
534 {
535 public:
536     QDomText();
537     QDomText(const QDomText& x);
538     QDomText& operator= (const QDomText&);
539
540     // DOM functions
541     QDomText splitText(int offset);
542
543     // Overridden from QDomCharacterData
544     inline QDomNode::NodeType nodeType() const { return TextNode; }
545
546 private:
547     QDomText(QDomTextPrivate*);
548
549     friend class QDomCDATASection;
550     friend class QDomDocument;
551     friend class QDomNode;
552 };
553
554 class Q_XML_EXPORT QDomComment : public QDomCharacterData
555 {
556 public:
557     QDomComment();
558     QDomComment(const QDomComment& x);
559     QDomComment& operator= (const QDomComment&);
560
561     // Overridden from QDomCharacterData
562     inline QDomNode::NodeType nodeType() const { return CommentNode; }
563
564 private:
565     QDomComment(QDomCommentPrivate*);
566
567     friend class QDomDocument;
568     friend class QDomNode;
569 };
570
571 class Q_XML_EXPORT QDomCDATASection : public QDomText
572 {
573 public:
574     QDomCDATASection();
575     QDomCDATASection(const QDomCDATASection& x);
576     QDomCDATASection& operator= (const QDomCDATASection&);
577
578     // Overridden from QDomText
579     inline QDomNode::NodeType nodeType() const { return CDATASectionNode; }
580
581 private:
582     QDomCDATASection(QDomCDATASectionPrivate*);
583
584     friend class QDomDocument;
585     friend class QDomNode;
586 };
587
588 class Q_XML_EXPORT QDomNotation : public QDomNode
589 {
590 public:
591     QDomNotation();
592     QDomNotation(const QDomNotation& x);
593     QDomNotation& operator= (const QDomNotation&);
594
595     // DOM read only attributes
596     QString publicId() const;
597     QString systemId() const;
598
599     // Overridden from QDomNode
600     inline QDomNode::NodeType nodeType() const { return NotationNode; }
601
602 private:
603     QDomNotation(QDomNotationPrivate*);
604
605     friend class QDomDocument;
606     friend class QDomNode;
607 };
608
609 class Q_XML_EXPORT QDomEntity : public QDomNode
610 {
611 public:
612     QDomEntity();
613     QDomEntity(const QDomEntity& x);
614     QDomEntity& operator= (const QDomEntity&);
615
616     // DOM read only attributes
617     QString publicId() const;
618     QString systemId() const;
619     QString notationName() const;
620
621     // Overridden from QDomNode
622     inline QDomNode::NodeType nodeType() const { return EntityNode; }
623
624 private:
625     QDomEntity(QDomEntityPrivate*);
626
627     friend class QDomNode;
628 };
629
630 class Q_XML_EXPORT QDomEntityReference : public QDomNode
631 {
632 public:
633     QDomEntityReference();
634     QDomEntityReference(const QDomEntityReference& x);
635     QDomEntityReference& operator= (const QDomEntityReference&);
636
637     // Overridden from QDomNode
638     inline QDomNode::NodeType nodeType() const { return EntityReferenceNode; }
639
640 private:
641     QDomEntityReference(QDomEntityReferencePrivate*);
642
643     friend class QDomDocument;
644     friend class QDomNode;
645 };
646
647 class Q_XML_EXPORT QDomProcessingInstruction : public QDomNode
648 {
649 public:
650     QDomProcessingInstruction();
651     QDomProcessingInstruction(const QDomProcessingInstruction& x);
652     QDomProcessingInstruction& operator= (const QDomProcessingInstruction&);
653
654     // DOM read only attributes
655     QString target() const;
656
657     // DOM attributes
658     QString data() const;
659     void setData(const QString& d);
660
661     // Overridden from QDomNode
662     inline QDomNode::NodeType nodeType() const { return ProcessingInstructionNode; }
663
664 private:
665     QDomProcessingInstruction(QDomProcessingInstructionPrivate*);
666
667     friend class QDomDocument;
668     friend class QDomNode;
669 };
670
671
672 Q_XML_EXPORT QTextStream& operator<<(QTextStream&, const QDomNode&);
673
674 #endif // QT_NO_DOM
675
676 QT_END_NAMESPACE
677
678 QT_END_HEADER
679
680 #endif // QDOM_H