1/**************************************************************************** 2** 3** Copyright (C) 2020 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the documentation of the Qt Toolkit. 7** 8** $QT_BEGIN_LICENSE:FDL$ 9** Commercial License Usage 10** Licensees holding valid commercial Qt licenses may use this file in 11** accordance with the commercial license agreement provided with the 12** Software or, alternatively, in accordance with the terms contained in 13** a written agreement between you and The Qt Company. For licensing terms 14** and conditions see https://www.qt.io/terms-conditions. For further 15** information use the contact form at https://www.qt.io/contact-us. 16** 17** GNU Free Documentation License Usage 18** Alternatively, this file may be used under the terms of the GNU Free 19** Documentation License version 1.3 as published by the Free Software 20** Foundation and appearing in the file included in the packaging of 21** this file. Please review the following information to ensure 22** the GNU Free Documentation License version 1.3 requirements 23** will be met: https://www.gnu.org/licenses/fdl-1.3.html. 24** $QT_END_LICENSE$ 25** 26****************************************************************************/ 27 28/*! 29 \group xml-tools 30 \title XML Classes 31 32 \brief Classes that support XML. 33 34 These classes are relevant to XML users. 35 36 \generatelist{related} 37*/ 38 39/*! 40 \page xml-processing.html 41 \title XML Processing 42 43 \brief An Overview of the XML processing facilities in Qt. 44 45 Qt provides two general-purpose sets of APIs to read and write well-formed 46 XML: \l{XML Streaming}{stream based} and 47 \l{Working with the DOM Tree}{DOM based}. 48 49 Qt also provides specific support for some XML dialects. For instance, the 50 Qt SVG module provides the QSvgRenderer and QSvgGenerator classes to read 51 and write a subset of SVG, an XML-based file 52 format. Qt also provides helper functions that may be useful to 53 those working with XML and XHTML: see Qt::escape() and 54 Qt::convertFromPlainText(). 55 56 \section1 Topics: 57 58 \list 59 \li \l {Classes for XML Processing} 60 \li \l {An Introduction to Namespaces} 61 \li \l {XML Streaming} 62 \li \l {Working with the DOM Tree} 63 \endlist 64 65 \section1 Classes for XML Processing 66 67 These classes are relevant to XML users. 68 69 \annotatedlist xml-tools 70*/ 71 72/*! 73 \page xml-namespaces.html 74 \title An Introduction to Namespaces 75 \target namespaces 76 77 \nextpage XML Streaming 78 79 Parts of the Qt XML module documentation assume that you are familiar 80 with XML namespaces. Here we present a brief introduction; skip to 81 \l{#namespacesConventions}{Qt XML documentation conventions} 82 if you already know this material. 83 84 Namespaces are a concept introduced into XML to allow a more modular 85 design. With their help data processing software can easily resolve 86 naming conflicts in XML documents. 87 88 Consider the following example: 89 90 \snippet code/doc_src_qtxml.qdoc 6 91 92 Here we find three different uses of the name \e title. If you wish to 93 process this document you will encounter problems because each of the 94 \e titles should be displayed in a different manner -- even though 95 they have the same name. 96 97 The solution would be to have some means of identifying the first 98 occurrence of \e title as the title of a book, i.e. to use the \e 99 title element of a book namespace to distinguish it from, for example, 100 the chapter title, e.g.: 101 \snippet code/doc_src_qtxml.qdoc 7 102 103 \e book in this case is a \e prefix denoting the namespace. 104 105 Before we can apply a namespace to element or attribute names we must 106 declare it. 107 108 Namespaces are URIs like \e http://www.example.com/fnord/book/. This 109 does not mean that data must be available at this address; the URI is 110 simply used to provide a unique name. 111 112 We declare namespaces in the same way as attributes; strictly speaking 113 they \e are attributes. To make for example \e 114 http://www.example.com/fnord/ the document's default XML namespace \e 115 xmlns we write 116 117 \snippet code/doc_src_qtxml.qdoc 8 118 119 To distinguish the \e http://www.example.com/fnord/book/ namespace from 120 the default, we must supply it with a prefix: 121 122 \snippet code/doc_src_qtxml.qdoc 9 123 124 A namespace that is declared like this can be applied to element and 125 attribute names by prepending the appropriate prefix and a ":" 126 delimiter. We have already seen this with the \e book:title element. 127 128 Element names without a prefix belong to the default namespace. This 129 rule does not apply to attributes: an attribute without a prefix does 130 not belong to any of the declared XML namespaces at all. Attributes 131 always belong to the "traditional" namespace of the element in which 132 they appear. A "traditional" namespace is not an XML namespace, it 133 simply means that all attribute names belonging to one element must be 134 different. Later we will see how to assign an XML namespace to an 135 attribute. 136 137 Due to the fact that attributes without prefixes are not in any XML 138 namespace there is no collision between the attribute \e title (that 139 belongs to the \e author element) and for example the \e title element 140 within a \e chapter. 141 142 Let's clarify this with an example: 143 \snippet code/doc_src_qtxml.qdoc 10 144 145 Within the \e document element we have two namespaces declared. The 146 default namespace \e http://www.example.com/fnord/ applies to the \e 147 book element, the \e chapter element, the appropriate \e title element 148 and of course to \e document itself. 149 150 The \e book:author and \e book:title elements belong to the namespace 151 with the URI \e http://www.example.com/fnord/book/. 152 153 The two \e book:author attributes \e title and \e name have no XML 154 namespace assigned. They are only members of the "traditional" 155 namespace of the element \e book:author, meaning that for example two 156 \e title attributes in \e book:author are forbidden. 157 158 In the above example we circumvent the last rule by adding a \e title 159 attribute from the \e http://www.example.com/fnord/ namespace to \e 160 book:author: the \e fnord:title comes from the namespace with the 161 prefix \e fnord that is declared in the \e book:author element. 162 163 Clearly the \e fnord namespace has the same namespace URI as the 164 default namespace. So why didn't we simply use the default namespace 165 we'd already declared? The answer is quite complex: 166 \list 167 \li attributes without a prefix don't belong to any XML namespace at 168 all, not even to the default namespace; 169 \li additionally omitting the prefix would lead to a \e title-title clash; 170 \li writing it as \e xmlns:title would declare a new namespace with the 171 prefix \e title instead of applying the default \e xmlns namespace. 172 \endlist 173 174 With the Qt XML classes elements and attributes can be accessed in two 175 ways: either by referring to their qualified names consisting of the 176 namespace prefix and the "real" name (or \e local name) or by the 177 combination of local name and namespace URI. 178 179 More information on XML namespaces can be found at 180 \l http://www.w3.org/TR/REC-xml-names/. 181 182 \target namespacesConventions 183 \section1 Conventions Used in the Qt XML Documentation 184 185 The following terms are used to distinguish the parts of names within 186 the context of namespaces: 187 \list 188 \li The \e {qualified name} 189 is the name as it appears in the document. (In the above example \e 190 book:title is a qualified name.) 191 \li A \e {namespace prefix} in a qualified name 192 is the part to the left of the ":". (\e book is the namespace prefix in 193 \e book:title.) 194 \li The \e {local part} of a name (also referred to as the \e {local 195 name}) appears to the right of the ":". (Thus \e title is the 196 local part of \e book:title.) 197 \li The \e {namespace URI} ("Uniform Resource Identifier") is a unique 198 identifier for a namespace. It looks like a URL 199 (e.g. \e http://www.example.com/fnord/ ) but does not require 200 data to be accessible by the given protocol at the named address. 201 \endlist 202 203 Elements without a ":" (like \e chapter in the example) do not have a 204 namespace prefix. In this case the local part and the qualified name 205 are identical (i.e. \e chapter). 206 207 \sa {DOM Bookmarks Example} 208*/ 209 210/*! 211 \page xml-streaming.html 212 \title XML Streaming 213 214 \previouspage An Introduction to Namespaces 215 \nextpage Working with the DOM Tree 216 217 Qt provides two classes for reading and writing XML through a simple streaming 218 API: QXmlStreamReader and QXmlStreamWriter. 219 220 A stream reader reports an XML document as a stream 221 of tokens. This differs from SAX as SAX applications provide handlers to 222 receive XML events from the parser whereas the QXmlStreamReader drives the 223 loop, pulling tokens from the reader when they are needed. 224 This pulling approach makes it possible to build recursive descent parsers, 225 allowing XML parsing code to be split into different methods or classes. 226 227 QXmlStreamReader is a well-formed XML 1.0 parser that excludes external 228 parsed entities. Hence, data provided by the stream reader adheres to the 229 W3C's criteria for well-formed XML, as long as no error occurs. Otherwise, 230 functions such as \l{QXmlStreamReader::atEnd()}{atEnd()}, 231 \l{QXmlStreamReader::error()}{error()} and \l{QXmlStreamReader::hasError()} 232 {hasError()} can be used to check and view the errors. 233 234 An example of QXmlStreamReader implementation would be the \c XbelReader in 235 \l{QXmlStream Bookmarks Example}, which wraps a QXmlStreamReader. 236 The constructor takes \a treeWidget as a parameter and the class has Xbel 237 specific functions: 238 239 \snippet streambookmarks/xbelreader.h 1 240 241 \dots 242 \snippet streambookmarks/xbelreader.h 2 243 \dots 244 245 The \c read() function accepts a QIODevice and sets it with 246 \l{QXmlStreamReader::setDevice()}{setDevice()}. The 247 \l{QXmlStreamReader::raiseError()}{raiseError()} function is used to 248 display a custom error message, inidicating that the file's version 249 is incorrect. 250 251 \snippet streambookmarks/xbelreader.cpp 1 252 253 The pendent to QXmlStreamReader is QXmlStreamWriter, which provides an XML 254 writer with a simple streaming API. QXmlStreamWriter operates on a 255 QIODevice and has specialized functions for all XML tokens or events you 256 want to write, such as \l{QXmlStreamWriter::writeDTD()}{writeDTD()}, 257 \l{QXmlStreamWriter::writeCharacters()}{writeCharacters()}, 258 \l{QXmlStreamWriter::writeComment()}{writeComment()} and so on. 259 260 To write XML document with QXmlStreamWriter, you start a document with the 261 \l{QXmlStreamWriter::writeStartDocument()}{writeStartDocument()} function 262 and end it with \l{QXmlStreamWriter::writeEndDocument()} 263 {writeEndDocument()}, which implicitly closes all remaining open tags. 264 Element tags are opened with \l{QXmlStreamWriter::writeStartDocument()} 265 {writeStartDocument()} and followed by 266 \l{QXmlStreamWriter::writeAttribute()}{writeAttribute()} or 267 \l{QXmlStreamWriter::writeAttributes()}{writeAttributes()}, 268 element content, and then \l{QXmlStreamWriter::writeEndDocument()} 269 {writeEndDocument()}. Also, \l{QXmlStreamWriter::writeEmptyElement()} 270 {writeEmptyElement()} can be used to write empty elements. 271 272 Element content comprises characters, entity references or nested elements. 273 Content can be written with \l{QXmlStreamWriter::writeCharacters()} 274 {writeCharacters()}, a function that also takes care of escaping all 275 forbidden characters and character sequences, 276 \l{QXmlStreamWriter::writeEntityReference()}{writeEntityReference()}, 277 or subsequent calls to \l{QXmlStreamWriter::writeStartElement()} 278 {writeStartElement()}. 279 280 The \c XbelWriter class from \l{QXmlStream Bookmarks Example} wraps a 281 QXmlStreamWriter. Its \c writeFile() function illustrates the core 282 functions of QXmlStreamWriter mentioned above: 283 284 \snippet streambookmarks/xbelwriter.cpp 1 285*/ 286 287/*! 288 \page xml-dom.tml 289 \title Working with the DOM Tree 290 \target dom 291 292 \previouspage XML Streaming 293 294 DOM Level 2 is a W3C Recommendation for XML interfaces that maps the 295 constituents of an XML document to a tree structure. The specification 296 of DOM Level 2 can be found at \l{http://www.w3.org/DOM/}. 297 298 \target domIntro 299 \section1 Introduction to DOM 300 301 DOM provides an interface to access and change the content and 302 structure of an XML file. It makes a hierarchical view of the document 303 (a tree view). Thus -- in contrast to the streaming API provided 304 by QXmlStreamReader -- an object 305 model of the document is resident in memory after parsing which makes 306 manipulation easy. 307 308 All DOM nodes in the document tree are subclasses of \l QDomNode. The 309 document itself is represented as a \l QDomDocument object. 310 311 Here are the available node classes and their potential child classes: 312 313 \list 314 \li \l QDomDocument: Possible children are 315 \list 316 \li \l QDomElement (at most one) 317 \li \l QDomProcessingInstruction 318 \li \l QDomComment 319 \li \l QDomDocumentType 320 \endlist 321 \li \l QDomDocumentFragment: Possible children are 322 \list 323 \li \l QDomElement 324 \li \l QDomProcessingInstruction 325 \li \l QDomComment 326 \li \l QDomText 327 \li \l QDomCDATASection 328 \li \l QDomEntityReference 329 \endlist 330 \li \l QDomDocumentType: No children 331 \li \l QDomEntityReference: Possible children are 332 \list 333 \li \l QDomElement 334 \li \l QDomProcessingInstruction 335 \li \l QDomComment 336 \li \l QDomText 337 \li \l QDomCDATASection 338 \li \l QDomEntityReference 339 \endlist 340 \li \l QDomElement: Possible children are 341 \list 342 \li \l QDomElement 343 \li \l QDomText 344 \li \l QDomComment 345 \li \l QDomProcessingInstruction 346 \li \l QDomCDATASection 347 \li \l QDomEntityReference 348 \endlist 349 \li \l QDomAttr: Possible children are 350 \list 351 \li \l QDomText 352 \li \l QDomEntityReference 353 \endlist 354 \li \l QDomProcessingInstruction: No children 355 \li \l QDomComment: No children 356 \li \l QDomText: No children 357 \li \l QDomCDATASection: No children 358 \li \l QDomEntity: Possible children are 359 \list 360 \li \l QDomElement 361 \li \l QDomProcessingInstruction 362 \li \l QDomComment 363 \li \l QDomText 364 \li \l QDomCDATASection 365 \li \l QDomEntityReference 366 \endlist 367 \li \l QDomNotation: No children 368 \endlist 369 370 With \l QDomNodeList and \l QDomNamedNodeMap two collection classes 371 are provided: \l QDomNodeList is a list of nodes, 372 and \l QDomNamedNodeMap is used to handle unordered sets of nodes 373 (often used for attributes). 374 375 The \l QDomImplementation class allows the user to query features of the 376 DOM implementation. 377 378 To get started please refer to the \l QDomDocument documentation. 379 You might also want to take a look at the \l{DOM Bookmarks Example}, 380 which illustrates how to read and write an XML bookmark file (XBEL) 381 using DOM. 382*/ 383