1QDomDocument(3qt)                                            QDomDocument(3qt)
2
3
4

NAME

6       QDomDocument - Represents an XML document
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qdom.h>
13
14       Inherits QDomNode.
15
16   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

DESCRIPTION

74       The QDomDocument class represents an XML document.
75
76       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
80       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
88       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
94       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
99       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
107       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
113       It is possible to insert a node from another document into the document
114       using importNode().
115
116       You can obtain a list of all the elements that have a particular tag
117       with elementsByTagName() or with elementsByTagNameNS().
118
119       The QDom classes are typically used as follows:
120
121           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
146       Once doc and elem go out of scope, the whole internal tree representing
147       the XML document is deleted.
148
149       To create a document using DOM use code like this:
150
151           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
160       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
165       See also XML.
166

MEMBER FUNCTION DOCUMENTATION

QDomDocument::QDomDocument ()

169       Constructs an empty document.
170

explicit QDomDocument::QDomDocument ( const QString & name )

172       Creates a document and sets the name of the document type to name.
173

explicit QDomDocument::QDomDocument ( const QDomDocumentType & doctype )

175       Creates a document with the document type doctype.
176
177       See also QDomImplementation::createDocumentType().
178

QDomDocument::QDomDocument ( const QDomDocument & x )

180       Constructs a copy of x.
181
182       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

QDomDocument::~QDomDocument ()

187       Destroys the object and frees its resources.
188

QDomAttr QDomDocument::createAttribute ( const QString & name )

190       Creates a new attribute called name that can be inserted into an
191       element, e.g. using QDomElement::setAttributeNode().
192
193       See also createAttributeNS().
194

QDomAttr QDomDocument::createAttributeNS ( const QString & nsURI, const

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
202       See also createAttribute().
203

QDomCDATASection QDomDocument::createCDATASection ( const QString & value )

205       Creates a new CDATA section for the string value that can be inserted
206       into the document, e.g. using QDomNode::appendChild().
207
208       See also QDomNode::appendChild(), QDomNode::insertBefore(), and
209       QDomNode::insertAfter().
210

QDomComment QDomDocument::createComment ( const QString & value )

212       Creates a new comment for the string value that can be inserted into
213       the document, e.g. using QDomNode::appendChild().
214
215       See also QDomNode::appendChild(), QDomNode::insertBefore(), and
216       QDomNode::insertAfter().
217

QDomDocumentFragment QDomDocument::createDocumentFragment ()

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

QDomElement QDomDocument::createElement ( const QString & tagName )

223       Creates a new element called tagName that can be inserted into the DOM
224       tree, e.g. using QDomNode::appendChild().
225
226       See also createElementNS(), QDomNode::appendChild(),
227       QDomNode::insertBefore(), and QDomNode::insertAfter().
228

QDomElement QDomDocument::createElementNS ( const QString & nsURI, const

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
236       See also createElement().
237

QDomEntityReference QDomDocument::createEntityReference ( const QString & name

239       )
240       Creates a new entity reference called name that can be inserted into
241       the document, e.g. using QDomNode::appendChild().
242
243       See also QDomNode::appendChild(), QDomNode::insertBefore(), and
244       QDomNode::insertAfter().
245

QDomProcessingInstruction QDomDocument::createProcessingInstruction ( const

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
252       See also QDomNode::appendChild(), QDomNode::insertBefore(), and
253       QDomNode::insertAfter().
254

QDomText QDomDocument::createTextNode ( const QString & value )

256       Creates a text node for the string value that can be inserted into the
257       document tree, e.g. using QDomNode::appendChild().
258
259       Warning: All characters within an XML document must be in the range:
260
261       #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]
262
263       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
267       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
271       See also QDomNode::appendChild(), QDomNode::insertBefore(), and
272       QDomNode::insertAfter().
273

QDomDocumentType QDomDocument::doctype () const

275       Returns the document type of this document.
276

QDomElement QDomDocument::documentElement () const

278       Returns the root element of the document.
279

QDomElement QDomDocument::elementById ( const QString & elementId )

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
284       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

QDomNodeList QDomDocument::elementsByTagName ( const QString & tagname ) const

289
290       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
294       See also elementsByTagNameNS() and QDomElement::elementsByTagName().
295

QDomNodeList QDomDocument::elementsByTagNameNS ( const QString & nsURI, const

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
303       See also elementsByTagName() and QDomElement::elementsByTagNameNS().
304

QDomImplementation QDomDocument::implementation () const

306       Returns a QDomImplementation object.
307

QDomNode QDomDocument::importNode ( const QDomNode & importedNode, bool deep )

309
310       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
314       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
319       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
326       The behavior of this function is slightly different depending on the
327       node types: <center>.nf
328
329       </center>
330
331       See also QDomElement::setAttribute(), QDomNode::insertBefore(),
332       QDomNode::insertAfter(), QDomNode::replaceChild(),
333       QDomNode::removeChild(), and QDomNode::appendChild().
334

bool QDomDocument::isDocument () const [virtual]

336       Returns TRUE.
337
338       Reimplemented from QDomNode.
339

QDomNode::NodeType QDomDocument::nodeType () const [virtual]

341       Returns DocumentNode.
342
343       Reimplemented from QDomNode.
344

QDomDocument & QDomDocument::operator= ( const QDomDocument & x )

346       Assigns x to this DOM document.
347
348       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

bool QDomDocument::setContent ( const QByteArray & buffer, bool

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
359       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
364       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
369       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
373       If namespaceProcessing is FALSE, the functions QDomNode::prefix(),
374       QDomNode::localName() and QDomNode::namespaceURI() return
375       QString::null.
376
377       See also QDomNode::namespaceURI(), QDomNode::localName(),
378       QDomNode::prefix(), QString::isNull(), and QString::isEmpty().
379

bool QDomDocument::setContent ( const QCString & buffer, bool

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
386       This function reads the XML document from the C string buffer.
387
388       Warning: This function does not try to detect the encoding: instead it
389       assumes that the C string is UTF-8 encoded.
390

bool QDomDocument::setContent ( const QString & text, bool

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
397       This function reads the XML document from the string text. Since text
398       is already a Unicode string, no encoding detection is done.
399

bool QDomDocument::setContent ( QIODevice * dev, bool namespaceProcessing,

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
405       This function reads the XML document from the IO device dev.
406

bool QDomDocument::setContent ( const QCString & buffer, QString * errorMsg =

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
412       This function reads the XML document from the C string buffer.
413
414       No namespace processing is performed.
415
416       Warning: This function does not try to detect the encoding: instead it
417       assumes that the C string is UTF-8 encoded.
418

bool QDomDocument::setContent ( const QByteArray & buffer, QString * errorMsg

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
424       This function reads the XML document from the byte array buffer.
425
426       No namespace processing is performed.
427

bool QDomDocument::setContent ( const QString & text, QString * errorMsg = 0,

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
433       This function reads the XML document from the string text. Since text
434       is already a Unicode string, no encoding detection is performed.
435
436       No namespace processing is performed either.
437

bool QDomDocument::setContent ( QIODevice * dev, QString * errorMsg = 0, int *

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
443       This function reads the XML document from the IO device dev.
444
445       No namespace processing is performed.
446

bool QDomDocument::setContent ( QXmlInputSource * source, QXmlReader * reader,

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
452       This function reads the XML document from the QXmlInputSource source
453       and parses it with the QXmlReader reader.
454
455       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
459       See also QXmlSimpleReader.
460

QCString QDomDocument::toCString () const

462       Converts the parsed document back to its textual representation and
463       returns a QCString for that is encoded in UTF-8.
464
465       See also toString().
466

QCString QDomDocument::toCString ( int indent ) const

468       This is an overloaded member function, provided for convenience. It
469       behaves essentially like the above function.
470
471       This function uses indent as the amount of space to indent subelements.
472

QString QDomDocument::toString () const

474       Converts the parsed document back to its textual representation.
475
476       See also toCString().
477

QString QDomDocument::toString ( int indent ) const

479       This is an overloaded member function, provided for convenience. It
480       behaves essentially like the above function.
481
482       This function uses indent as the amount of space to indent subelements.
483
484

SEE ALSO

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

AUTHOR

495       Generated automatically from the source code.
496

BUGS

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
502       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
508       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).
511
512
513
514Trolltech AS                    2 February 2007              QDomDocument(3qt)
Impressum