Revision control
Copy as Markdown
// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page xml-changes-qt6.html
\title Changes to Qt XML
\ingroup changes-qt-5-to-6
\brief Use QXmlStreamReader for reading XML files.
Qt 6 is a result of the conscious effort to make the framework more
efficient and easy to use.
We try to maintain binary and source compatibility for all the public
APIs in each release. But some changes were inevitable in an effort to
make Qt a better framework and align with modern standards.
Qt 6 enforces XML 1.0 rules more strictly than Qt 5. In Qt 5,the XML
parser was more lenient, allowing certain constructs that were not
compliant with the XML 1.0 specification.
Qt 6 corrects this behavior, ensuring that XML handling follows
the standard properly. If your application relies on behavior
that was incorrectly permitted in Qt 5, you may need to adjust your
XML documents or processing logic accordingly.
For more details on XML 1.0 rules, see the official W3C XML specification:
In this topic we summarize those changes in Qt XML, and provide
guidance to handle them.
\section1 Simple API for XML (SAX) parser
All \b SAX classes have been removed from Qt XML. Use
QXmlStreamReader for reading XML files. Here are some simple steps to
port your current code to QXmlStreamReader:
For example, if you have code like
\code
QFile *file = new QFile(...);
QXmlInputSource *source = new QXmlInputSource(file);
Handler *handler = new Handler;
QXmlSimpleReader xmlReader;
xmlReader.setErrorHandler(handler);
xmlReader.setContentHandler(handler);
if (xmlReader.parse(source)) {
... // do processing
} else {
... // do error handling
}
\endcode
you can rewrite it as
\code
QFile file = ...;
QXmlStreamReader reader(&file);
while (!reader.atEnd()) {
reader.readNext();
... // do processing
}
if (reader.hasError()) {
... // do error handling
}
\endcode
\section2 QDom and QDomDocument
As \b SAX classes have been removed from Qt XML, QDomDocument
has been re-implemented using QXmlStreamReader.
This causes a few behavioral changes:
\list
\li Attribute values will be normalized. For example,
\c{<tag attr=" a \n b " />} is equivalent to \c{<tag attr="a b"/>}.
\li Identical qualified attribute names are no longer allowed. This
means attributes of an element must have unique names.
\li Undeclared namespace prefixes are no longer allowed.
\endlist
For more details see:
\section2 Control characters
In Qt 6, control characters such as U+0000—U+001F, U+007F, and U+0080—U+009F
are now correctly rejected per XML 1.0 rules.
They were incorrectly allowed in Qt 5.
Before using XML with Qt6 ensure that your XML documents contain only valid
XML 1.0-compliant characters. If control characters are necessary, encode
them using text-safe format.
For more details see:
\section2 HTML Entities in XML
In Qt 6, HTML entities are no longer valid unless explicitly declared in a
Document Type Definition (DTD). In Qt 5, certain HTML-specific entities
(e.g., \c{ }) were allowed, even without declaration. To ensure
compatibility in Qt 6 use numeric character references, define required
entities in a DTD or if your content relies on HTML entities, process
the XML as HTML instead.
For more details see:
\section2 Spacing-only text nodes
By default, text nodes containing only spacing characters are stripped
and won't appear in the QDomDocument. The Qt 5 way of changing this behavior
was using the QDomDocument::setContent() overload that allowed a \c QXmlReader
to be supplied. That overload was removed in Qt 6.0, but since Qt 6.5,
you can pass QDomDocument::ParseOption::PreserveSpacingOnlyNodes as a parse
option, to specify that spacing-only text nodes must be preserved.
If you use QDomDocument and rely on any of these, you must update
your code and XML documents accordingly.
\section1 Qt Core5 compatibility library
If your application or library cannot be ported right now, the \l
QXmlSimpleReader and related classes still exist in Qt5Compat to keep
old code-bases working. If you want to use those SAX classes further, you
need to link against the new Qt5Compat module and add this line to your \l
qmake \c .pro file:
\code
QT += core5compat
\endcode
In case you already ported your application or library to the
\l {Build with CMake}{cmake} build system, add the following to your
\c CMakeList.txt:
\code
PUBLIC_LIBRARIES
Qt::Core5Compat
\endcode
*/