1QDomDocument(3qt) QDomDocument(3qt)
2
6 QDomDocument - Represents an XML document
7
9 All the functions in this class are reentrant when Qt is built with
10 thread support.</p>
11 #include <qdom.h>
13 Inherits QDomNode.
15 Public Members
17 QDomDocument ()
18 explicit QDomDocument ( const QString & name )
19 explicit QDomDocument ( const QDomDocumentType & doctype )
20 QDomDocument ( const QDomDocument & x )
21 QDomDocument & operator= ( const QDomDocument & x )
22 ~QDomDocument ()
23 QDomElement createElement ( const QString & tagName )
24 QDomDocumentFragment createDocumentFragment ()
25 QDomText createTextNode ( const QString & value )
26 QDomComment createComment ( const QString & value )
27 QDomCDATASection createCDATASection ( const QString & value )
28 QDomProcessingInstruction createProcessingInstruction ( const QString &
29 target, const QString & data )
30 QDomAttr createAttribute ( const QString & name )
31 QDomEntityReference createEntityReference ( const QString & name )
32 QDomNodeList elementsByTagName ( const QString & tagname ) const
33 QDomNode importNode ( const QDomNode & importedNode, bool deep )
34 QDomElement createElementNS ( const QString & nsURI, const QString &
35 qName )
36 QDomAttr createAttributeNS ( const QString & nsURI, const QString &
37 qName )
38 QDomNodeList elementsByTagNameNS ( const QString & nsURI, const QString
39 & localName )
40 QDomElement elementById ( const QString & elementId )
41 QDomDocumentType doctype () const
42 QDomImplementation implementation () const
43 QDomElement documentElement () const
44 bool setContent ( const QCString & buffer, bool namespaceProcessing,
45 QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0
46 )
47 bool setContent ( const QByteArray & buffer, bool namespaceProcessing,
48 QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0
49 )
50 bool setContent ( const QString & text, bool namespaceProcessing,
51 QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0
52 )
53 bool setContent ( QIODevice * dev, bool namespaceProcessing, QString *
54 errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
55 bool setContent ( const QCString & buffer, QString * errorMsg = 0, int
56 * errorLine = 0, int * errorColumn = 0 )
57 bool setContent ( const QByteArray & buffer, QString * errorMsg = 0,
58 int * errorLine = 0, int * errorColumn = 0 )
59 bool setContent ( const QString & text, QString * errorMsg = 0, int *
60 errorLine = 0, int * errorColumn = 0 )
61 bool setContent ( QIODevice * dev, QString * errorMsg = 0, int *
62 errorLine = 0, int * errorColumn = 0 )
63 bool setContent ( QXmlInputSource * source, QXmlReader * reader,
64 QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0
65 )
66 virtual QDomNode::NodeType nodeType () const
67 virtual bool isDocument () const
68 QString toString () const
69 QString toString ( int indent ) const
70 QCString toCString () const
71 QCString toCString ( int indent ) const
72
74 The QDomDocument class represents an XML document.
75 The QDomDocument class represents the entire XML document.
77 Conceptually, it is the root of the document tree, and provides the
78 primary access to the document's data.
79 Since elements, text nodes, comments, processing instructions, etc.,
81 cannot exist outside the context of a document, the document class also
82 contains the factory functions needed to create these objects. The node
83 objects created have an ownerDocument() function which associates them
84 with the document within whose context they were created. The DOM
85 classes that will be used most often are QDomNode, QDomDocument,
86 QDomElement and QDomText.
87 The parsed XML is represented internally by a tree of objects that can
89 be accessed using the various QDom classes. All QDom classes only
90 reference objects in the internal tree. The internal objects in the DOM
91 tree will get deleted once the last QDom object referencing them and
92 the QDomDocument itself are deleted.
93 Creation of elements, text nodes, etc. is done using the various
95 factory functions provided in this class. Using the default
96 constructors of the QDom classes will only result in empty objects that
97 cannot be manipulated or inserted into the Document.
98 The QDomDocument class has several functions for creating document
100 data, for example, createElement(), createTextNode(), createComment(),
101 createCDATASection(), createProcessingInstruction(), createAttribute()
102 and createEntityReference(). Some of these functions have versions that
103 support namespaces, i.e. createElementNS() and createAttributeNS(). The
104 createDocumentFragment() function is used to hold parts of the
105 document; this is useful for manipulating for complex documents.
106 The entire content of the document is set with setContent(). This
108 function parses the string it is passed as an XML document and creates
109 the DOM tree that represents the document. The root element is
110 available using documentElement(). The textual representation of the
111 document can be obtained using toString().
112 It is possible to insert a node from another document into the document
114 using importNode().
115 You can obtain a list of all the elements that have a particular tag
117 with elementsByTagName() or with elementsByTagNameNS().
118 The QDom classes are typically used as follows:
120 QDomDocument doc( "mydocument" );
122 QFile file( "mydocument.xml" );
123 if ( !file.open( IO_ReadOnly ) )
124 return;
125 if ( !doc.setContent( &file ) ) {
126 file.close();
127 return;
128 }
129 file.close();
130 // print out the element names of all elements that are direct children
131 // of the outermost element.
132 QDomElement docElem = doc.documentElement();
133 QDomNode n = docElem.firstChild();
134 while( !n.isNull() ) {
135 QDomElement e = n.toElement(); // try to convert the node to an element.
136 if( !e.isNull() ) {
137 cout << e.tagName() << endl; // the node really is an element.
138 }
139 n = n.nextSibling();
140 }
141 // Here we append a new element to the end of the document
142 QDomElement elem = doc.createElement( "img" );
143 elem.setAttribute( "src", "myimage.png" );
144 docElem.appendChild( elem );
145 Once doc and elem go out of scope, the whole internal tree representing
147 the XML document is deleted.
148 To create a document using DOM use code like this:
150 QDomDocument doc( "MyML" );
152 QDomElement root = doc.createElement( "MyML" );
153 doc.appendChild( root );
154 QDomElement tag = doc.createElement( "Greeting" );
155 root.appendChild( tag );
156 QDomText t = doc.createTextNode( "Hello World" );
157 tag.appendChild( t );
158 QString xml = doc.toString();
159 For further information about the Document Object Model see
161 http://www.w3.org/TR/REC-DOM-Level-1/ and http://www.w3.org/TR/DOM-
162 Level-2-Core/. For a more general introduction of the DOM
163 implementation see the QDomDocument documentation.
164 See also XML.
166
169 Constructs an empty document.
170
172 Creates a document and sets the name of the document type to name.
173
175 Creates a document with the document type doctype.
176 See also QDomImplementation::createDocumentType().
178
180 Constructs a copy of x.
181 The data of the copy is shared (shallow copy): modifying one node will
183 also change the other. If you want to make a deep copy, use
184 cloneNode().
185
187 Destroys the object and frees its resources.
188
190 Creates a new attribute called name that can be inserted into an
191 element, e.g. using QDomElement::setAttributeNode().
192 See also createAttributeNS().
194
196 QString & qName )
197 Creates a new attribute with namespace support that can be inserted
198 into an element. The name of the attribute is qName and the namespace
199 URI is nsURI. This function also sets QDomNode::prefix() and
200 QDomNode::localName() to appropriate values (depending on qName).
201 See also createAttribute().
203
205 Creates a new CDATA section for the string value that can be inserted
206 into the document, e.g. using QDomNode::appendChild().
207 See also QDomNode::appendChild(), QDomNode::insertBefore(), and
209 QDomNode::insertAfter().
210
212 Creates a new comment for the string value that can be inserted into
213 the document, e.g. using QDomNode::appendChild().
214 See also QDomNode::appendChild(), QDomNode::insertBefore(), and
216 QDomNode::insertAfter().
217
219 Creates a new document fragment, that can be used to hold parts of the
220 document, e.g. when doing complex manipulations of the document tree.
221
223 Creates a new element called tagName that can be inserted into the DOM
224 tree, e.g. using QDomNode::appendChild().
225 See also createElementNS(), QDomNode::appendChild(),
227 QDomNode::insertBefore(), and QDomNode::insertAfter().
228
230 QString & qName )
231 Creates a new element with namespace support that can be inserted into
232 the DOM tree. The name of the element is qName and the namespace URI is
233 nsURI. This function also sets QDomNode::prefix() and
234 QDomNode::localName() to appropriate values (depending on qName).
235 See also createElement().
237
239 )
240 Creates a new entity reference called name that can be inserted into
241 the document, e.g. using QDomNode::appendChild().
242 See also QDomNode::appendChild(), QDomNode::insertBefore(), and
244 QDomNode::insertAfter().
245
247 QString & target, const QString & data )
248 Creates a new processing instruction that can be inserted into the
249 document, e.g. using QDomNode::appendChild(). This function sets the
250 target for the processing instruction to target and the data to data.
251 See also QDomNode::appendChild(), QDomNode::insertBefore(), and
253 QDomNode::insertAfter().
254
256 Creates a text node for the string value that can be inserted into the
257 document tree, e.g. using QDomNode::appendChild().
258 Warning: All characters within an XML document must be in the range:
260 #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
262 This rule also applies to characters encoded as character entities and
264 characters in CDATA sections. If you use this function to insert
265 characters outside of this range, the document will not be well-formed.
266 If you want to store binary data in an XML document you must either use
268 your own scheme to escape illegal characters, or you must store it in
269 an external unparsed entity.
270 See also QDomNode::appendChild(), QDomNode::insertBefore(), and
272 QDomNode::insertAfter().
273
275 Returns the document type of this document.
276
278 Returns the root element of the document.
279
281 Returns the element whose ID is equal to elementId. If no element with
282 the ID was found, this function returns a null element.
283 Since the QDomClasses do not know which attributes are element IDs,
285 this function returns always a null element. This may change in a
286 future version.
287
289 Returns a QDomNodeList, that contains all the elements in the document
291 with the name tagname. The order of the node list is the order they are
292 encountered in a preorder traversal of the element tree.
293 See also elementsByTagNameNS() and QDomElement::elementsByTagName().
295
297 QString & localName )
298 Returns a QDomNodeList that contains all the elements in the document
299 with the local name localName and a namespace URI of nsURI. The order
300 of the node list is the order they are encountered in a preorder
301 traversal of the element tree.
302 See also elementsByTagName() and QDomElement::elementsByTagNameNS().
304
306 Returns a QDomImplementation object.
307
309 Imports the node importedNode from another document to this document.
311 importedNode remains in the original document; this function creates a
312 copy that can be used within this document.
313 This function returns the imported node that belongs to this document.
315 The returned node has no parent. It is not possible to import
316 QDomDocument and QDomDocumentType nodes. In those cases this function
317 returns a null node.
318 If deep is TRUE, this function imports not only the node importedNode
320 but its whole subtree; if it is FALSE, only the importedNode is
321 imported. The argument deep has no effect on QDomAttr and
322 QDomEntityReference nodes, since the descendents of QDomAttr nodes are
323 always imported and those of QDomEntityReference nodes are never
324 imported.
325 The behavior of this function is slightly different depending on the
327 node types: <center>.nf
328 </center>
330 See also QDomElement::setAttribute(), QDomNode::insertBefore(),
332 QDomNode::insertAfter(), QDomNode::replaceChild(),
333 QDomNode::removeChild(), and QDomNode::appendChild().
334
336 Returns TRUE.
337 Reimplemented from QDomNode.
339
341 Returns DocumentNode.
342 Reimplemented from QDomNode.
344
346 Assigns x to this DOM document.
347 The data of the copy is shared (shallow copy): modifying one node will
349 also change the other. If you want to make a deep copy, use
350 cloneNode().
351
353 namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int *
354 errorColumn = 0 )
355 This function parses the XML document from the byte array buffer and
356 sets it as the content of the document. It tries to detect the encoding
357 of the document as required by the XML specification.
358 If namespaceProcessing is TRUE, the parser recognizes namespaces in the
360 XML file and sets the prefix name, local name and namespace URI to
361 appropriate values. If namespaceProcessing is FALSE, the parser does no
362 namespace processing when it reads the XML file.
363 If a parse error occurs, the function returns FALSE; otherwise it
365 returns TRUE. If a parse error occurs and errorMsg, errorLine and
366 errorColumn are not 0, the error message is placed in *errorMsg, the
367 line number *errorLine and the column number in *errorColumn.
368 If namespaceProcessing is TRUE, the function QDomNode::prefix() returns
370 a string for all elements and attributes. It returns an empty string if
371 the element or attribute has no prefix.
372 If namespaceProcessing is FALSE, the functions QDomNode::prefix(),
374 QDomNode::localName() and QDomNode::namespaceURI() return
375 QString::null.
376 See also QDomNode::namespaceURI(), QDomNode::localName(),
378 QDomNode::prefix(), QString::isNull(), and QString::isEmpty().
379
381 namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int *
382 errorColumn = 0 )
383 This is an overloaded member function, provided for convenience. It
384 behaves essentially like the above function.
385 This function reads the XML document from the C string buffer.
387 Warning: This function does not try to detect the encoding: instead it
389 assumes that the C string is UTF-8 encoded.
390
392 namespaceProcessing, QString * errorMsg = 0, int * errorLine = 0, int *
393 errorColumn = 0 )
394 This is an overloaded member function, provided for convenience. It
395 behaves essentially like the above function.
396 This function reads the XML document from the string text. Since text
398 is already a Unicode string, no encoding detection is done.
399
401 QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
402 This is an overloaded member function, provided for convenience. It
403 behaves essentially like the above function.
404 This function reads the XML document from the IO device dev.
406
408 0, int * errorLine = 0, int * errorColumn = 0 )
409 This is an overloaded member function, provided for convenience. It
410 behaves essentially like the above function.
411 This function reads the XML document from the C string buffer.
413 No namespace processing is performed.
415 Warning: This function does not try to detect the encoding: instead it
417 assumes that the C string is UTF-8 encoded.
418
420 = 0, int * errorLine = 0, int * errorColumn = 0 )
421 This is an overloaded member function, provided for convenience. It
422 behaves essentially like the above function.
423 This function reads the XML document from the byte array buffer.
425 No namespace processing is performed.
427
429 int * errorLine = 0, int * errorColumn = 0 )
430 This is an overloaded member function, provided for convenience. It
431 behaves essentially like the above function.
432 This function reads the XML document from the string text. Since text
434 is already a Unicode string, no encoding detection is performed.
435 No namespace processing is performed either.
437
439 errorLine = 0, int * errorColumn = 0 )
440 This is an overloaded member function, provided for convenience. It
441 behaves essentially like the above function.
442 This function reads the XML document from the IO device dev.
444 No namespace processing is performed.
446
448 QString * errorMsg = 0, int * errorLine = 0, int * errorColumn = 0 )
449 This is an overloaded member function, provided for convenience. It
450 behaves essentially like the above function.
451 This function reads the XML document from the QXmlInputSource source
453 and parses it with the QXmlReader reader.
454 This function doesn't change the features of the reader. If you want to
456 use certain features for parsing you can use this function to set up
457 the reader appropriate.
458 See also QXmlSimpleReader.
460
462 Converts the parsed document back to its textual representation and
463 returns a QCString for that is encoded in UTF-8.
464 See also toString().
466
468 This is an overloaded member function, provided for convenience. It
469 behaves essentially like the above function.
470 This function uses indent as the amount of space to indent subelements.
472
474 Converts the parsed document back to its textual representation.
475 See also toCString().
477
479 This is an overloaded member function, provided for convenience. It
480 behaves essentially like the above function.
481 This function uses indent as the amount of space to indent subelements.
483
486 http://doc.trolltech.com/qdomdocument.html
487 http://www.trolltech.com/faq/tech.html
488
490 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
491 license file included in the distribution for a complete license
492 statement.
493
495 Generated automatically from the source code.
496
498 If you find a bug in Qt, please report it as described in
499 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
500 help you. Thank you.
501 The definitive Qt documentation is provided in HTML format; it is
503 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
504 web browser. This man page is provided as a convenience for those users
505 who prefer man pages, although this format is not officially supported
506 by Trolltech.
507 If you find errors in this manual page, please report them to qt-
509 bugs@trolltech.com. Please include the name of the manual page
510 (qdomdocument.3qt) and the Qt version (3.3.8).
511Trolltech AS 2 February 2007 QDomDocument(3qt)