diff options
Diffstat (limited to 'src/corelib/doc/src/qt6-changes.qdoc')
| -rw-r--r-- | src/corelib/doc/src/qt6-changes.qdoc | 372 |
1 files changed, 104 insertions, 268 deletions
diff --git a/src/corelib/doc/src/qt6-changes.qdoc b/src/corelib/doc/src/qt6-changes.qdoc index b92144a699..011568ef75 100644 --- a/src/corelib/doc/src/qt6-changes.qdoc +++ b/src/corelib/doc/src/qt6-changes.qdoc @@ -1,35 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtcore-changes-qt6.html \title Changes to Qt Core \ingroup changes-qt-5-to-6 - \brief Migrate Qt Core to Qt 6. + \brief Changes to containers, strings, serialization and I/O classes. Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use. @@ -48,7 +24,7 @@ \section3 qHash() Signature For custom types, QHash and QMultiHash rely on you providing - a \l{The qHash() hashing function} {custom qHash() function} + a \l{qHash}{custom qHash() function} in the same namespace. In Qt 4 and Qt 5, the return value and optional second argument of a \c qHash function was of type \c uint. In Qt 6, it is \c size_t. @@ -70,12 +46,12 @@ \section3 Stability of References - The implementation of QHash and QMultiHash in Qt 6 got changed from + The implementation of QHash, QMultiHash and QSet in Qt 6 got changed from a node based approach to a two stage lookup table. This design allows to keep the memory overhead of a hash instance very small, while at the same time giving good performance. - One behavioral change to note is that the new QHash implementation + One behavioral change to note is that the new implementation will not provide stable references to elements in the hash when the table needs to grow, or when entries are removed. Applications that rely on such stability might now run into undefined behavior. @@ -307,7 +283,7 @@ \section1 String related classes - \section2 QStringView + \section2 The QStringView class Starting with Qt6 it is generally recommended to use \l QStringView over \c QStringRef. \l QStringView references a contiguous portion of a UTF-16 @@ -332,28 +308,15 @@ string += ...; \endcode - \section2 QStringRef + \section2 The QStringRef class In Qt6 \l QStringRef got removed from Qt Core. To ease porting of existing applications without touching the whole code-base, the \c QStringRef class did not vanish completely and instead it got moved into the Qt5Compat module. - - If you want to use \c QStringRef 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 + If you want to use \c QStringRef further, see \l {Using the Qt5Compat module}. Unfortunately, some methods exposed by \l QString returning a \c QStringRef, - could not be moved to Qt5Compat. Therefore some manually porting may be + could not be moved to Qt5Compat. Therefore some manual porting may be needed. If your code uses one or more of the following functions you need to port them to use \l QStringView or \l QStringTokenizer. It is also recommended to use \l {QStringView::tokenize} over \l {QStringView::split} @@ -392,9 +355,18 @@ } \endcode + \section1 QMutex and Related Classes + + In Qt 6, QRecursiveMutex does not inherit from QMutex anymore. This change was + done to improve the performance of both QMutex and QRecursiveMutex. + + Due to those changes, the QMutex::RecursionMode enum has been removed, and + QMutexLocker is now a templated class that can operate on both QMutex and + QRecursiveMutex. + \section1 QFuture and Related Classes - \section2 QFuture + \section2 The QFuture class To avoid unintended usage of QFuture, there were some changes to QFuture API in Qt 6, which may introduce source compatibility breaks. @@ -459,16 +431,20 @@ code that was using QFuture with QtConcurrent. Only the code that was using it with the undocumented \c QFutureInterface may be affected. + \li QFutureWatcher::isFinished() now reflects the finished-state of the + QFuture rather than returning false until QFutureWatcher::finished() has + been emitted. + \endlist - \section2 QPromise + \section2 The QPromise class In Qt 6, the new QPromise class should be used instead of unofficial QFutureInterface as a "setter" counterpart of QFuture. \section1 IO Classes - \section2 QProcess + \section2 The QProcess class In Qt 6, the QProcess::start() overload that interprets a single command string by splitting it into program name and arguments is renamed to QProcess::startCommand(). @@ -499,7 +475,7 @@ \section1 Meta-Type system - \section2 QVariant + \section2 The QVariant class \c QVariant has been rewritten to use \c QMetaType for all of its operations. This implies behavior changes in a few methods: @@ -509,7 +485,7 @@ \li \c QVariant::isNull() now only returns \c true if the \c QVariant is empty or contains a \c nullptr. In Qt 5, it also returned true for classes in qtbase which had an \c isNull method themselves if that one returned true. Code relying on the old behavior needs to check whether - the contained value returs isNull – however such code is unlikely to occur in practice, as + the contained value returns isNull – however such code is unlikely to occur in practice, as \c isNull() is rarely the property one is interested in (compare \c QString::isEmpty() / \c isNull() and \c QTime::isValid / \c isNull). @@ -520,9 +496,13 @@ \endlist - \section2 QMetaType + Furthermore, QVariant::operator<, QVariant::operator<=, QVariant::operator> and + QVariant::operator>= were removed, because different variants are not always orderable. This + also means that QVariant cannot be used anymore as a key in a QMap. + + \section2 The QMetaType class - In Qt 6, registration of comparators, and \cQDebug and \QDataStream streaming operators is + In Qt 6, registration of comparators, and QDebug and QDataStream streaming operators is done automatically. Consequently, \c QMetaType::registerEqualsComparator(), \c QMetaType::registerComparators(), \c qRegisterMetaTypeStreamOperators() and \c QMetaType::registerDebugStreamOperator() do no longer exist. Calls to those methods @@ -546,251 +526,107 @@ \section1 Regular expression classes - \section2 QRegularExpression - - In Qt6, all methods taking the \c QRegExp got removed from our code-base. - Therefore it is very likely that you will have to port your application or - library to \l QRegularExpression. - - \l QRegularExpression implements Perl-compatible regular expressions. It - fully supports Unicode. For an overview of the regular expression syntax - supported by \l QRegularExpression, please refer to the aforementioned - pcrepattern(3) man page. A regular expression is made up of two things: a - pattern string and a set of pattern options that change the meaning of the - pattern string. - - There are some subtle differences between \l QRegularExpression and \c - QRegExp that will be explained by this document to ease the porting effort. - - \l QRegularExpression is more strict when it comes to the syntax of the - regular expression. Therefore it is always good to check the expression - for \l {QRegularExpression::isValid}{validity}. - - \l QRegularExpression can almost always be declared const (except when the - pattern changes), while \c QRegExp almost never could be. - - There is no replacement for the \l {QRegExp::CaretMode}{CaretMode} - enumeration. The \l {QRegularExpression::AnchoredMatchOption} match option - can be used to emulate the QRegExp::CaretAtOffset behavior. There is no - equivalent for the other QRegExp::CaretMode modes. - - \l QRegularExpression supports only Perl-compatible regular expressions. - Still, it does not support all the features available in Perl-compatible - regular expressions. The most notable one is the fact that duplicated names - for capturing groups are not supported, and using them can lead to - undefined behavior. This may change in a future version of Qt. - - \section3 Wildcard matching - - There is no direct way to do wildcard matching in \l QRegularExpression. - However, the \l {QRegularExpression::wildcardToRegularExpression} method - is provided to translate glob patterns into a Perl-compatible regular - expression that can be used for that purpose. - - \oldcode - QRegExp wildcard("*.txt"); - wildcard.setPatternSyntax(QRegExp::Wildcard); - \newcode - auto wildcard = QRegularExpression(QRegularExpression::wildcardToRegularExpression("*.txt")); - \endcode - - Please note though that not all shell like wildcard pattern might be - translated in a way you would expect it. The following example code will - silently break if simply converted using the above mentioned function: - - \code * - const QString fp1("C:/Users/dummy/files/content.txt"); - const QString fp2("/home/dummy/files/content.txt"); - - QRegExp re1("\1/files/*"); - re1.setPatternSyntax(QRegExp::Wildcard); - ... = re1.exactMatch(fp1); // returns true - ... = re1.exactMatch(fp2); // returns true + \section2 The QRegularExpression class - // but converted with QRegularExpression::wildcardToRegularExpression() + In Qt 6, the \c QRegExp type has been retired to the Qt5Compat module + and all Qt APIs using it have been removed from other modules. + Client code which used it can be ported to use \l QRegularExpression + in its place. As \l QRegularExpression is present already in Qt 5, + this can be done and tested before migration to Qt 6. - QRegularExpression re2(QRegularExpression::wildcardToRegularExpression("\1/files/*")); - ... = re2.match(fp1).hasMatch(); // returns false - ... = re2.match(fp2).hasMatch(); // returns false - \endcode - - \section3 Searching forward - - Forward searching inside a string was usually implemented with a loop using - \c {QRegExp::indexIn} and a growing offset, but can now be easily implemented - with \l QRegularExpressionMatchIterator or \l {QString::indexOf}. - - \oldcode - QString subject("the quick fox"); - - int offset = 0; - QRegExp re("(\\w+)"); - while ((offset = re.indexIn(subject, offset)) != -1) { - offset += re.matchedLength(); - // ... - } - \newcode - QRegularExpression re("(\\w+)"); - QString subject("the quick fox"); - - QRegularExpressionMatchIterator i = re.globalMatch(subject); - while (i.hasNext()) { - QRegularExpressionMatch match = i.next(); - // ... - } + \include corelib/port-from-qregexp.qdocinc porting-to-qregularexpression - // or alternatively using QString::indexOf + \section2 The QRegExp class - qsizetype from = 0; - QRegularExpressionMatch match; - while ((from = subject.indexOf(re, from, &match)) != -1) { - from += match.capturedLength(); - // ... - } - \endcode - - \section3 Searching backwards - - Backwards searching inside a string was usually often implemented as a loop - over \c {QRegExp::lastIndexIn}, but can now be easily implemented using - \l {QString::lastIndexOf} and \l {QRegularExpressionMatch}. - - \note \l QRegularExpressionMatchIterator is not capable of performing a - backwards search. + In Qt6 \l QRegExp got removed from Qt Core. If your application cannot be + ported right now, \c QRegExp still exists in Qt5Compat to keep these + code-bases working. If you want to use \c QRegExp further, see + \l {Using the Qt5Compat module}. - \oldcode - int offset = -1; - QString subject("Lorem ipsum dolor sit amet, consetetur sadipscing."); + \section1 QEvent and subclasses - QRegExp re("\\s+([ids]\\w+)"); - while ((offset = re.lastIndexIn(subject, offset)) != -1) { - --offset; - // ... - } - \newcode - qsizetype from = -1; - QString subject("Lorem ipsum dolor sit amet, consetetur sadipscing."); - - QRegularExpressionMatch match; - QRegularExpression re("\\s+([ids]\\w+)"); - while ((from = subject.lastIndexOf(re, from, &match)) != -1) { - --from; - // ... - } - \endcode + The QEvent class defined a copy constructor and an assignment operator, + in spite of being a polymorphic class. Copying classes with virtual methods + can result in slicing when assigning objects from different classes to each + other. Since copying and assigning often happens implicilty, this could + lead to hard-to-debug problems. - \section3 exactMatch vs. match.hasMatch + In Qt 6, the copy constructor and assignment operator for QEvent subclasses + have been made protected to prevent implicit copying. If you need to copy + events, use the \l{QEvent::}{clone} method, which will return a heap-allocated + copy of the QEvent object. Make sure you delete the clone, perhaps using + std::unique_ptr, unless you post it (in which case Qt will delete it once it + has been delivered). - \c {QRegExp::exactMatch} served two purposes: it exactly matched a regular - expression against a subject string, and it implemented partial matching. - Exact matching indicates whether the regular expression matches the entire - subject string. For example: + In your QEvent subclasses, override clone(), and declare the protected and + default-implemented copy constructor and assignment operator like this: \code - QString source("abc123"); + class MyEvent : public QEvent + { + public: + // ... - QRegExp("\\d+").exactMatch(source); // returns false - QRegExp("[a-z]+\\d+").exactMatch(source); // returns true + MyEvent *clone() const override { return new MyEvent(*this); } - QRegularExpression("\\d+").match(source).hasMatch(); // returns true - QRegularExpression("[a-z]+\\d+").match(source).hasMatch(); // returns true + protected: + MyEvent(const MyEvent &other) = default; + MyEvent &operator=(const MyEvent &other) = default; + MyEvent(MyEvent &&) = delete; + MyEvent &operator=(MyEvent &&) = delete; + // member data + }; \endcode - Exact matching is not reflected in \l QRegularExpression. If you want to be - sure that the subject string matches the regular expression exactly, you - can wrap the pattern using the \l {QRegularExpression::anchoredPattern} - function: - - \code - QString source("abc123"); - - QString pattern("\\d+"); - QRegularExpression(pattern).match(source).hasMatch(); // returns true + Note that if your MyEvent class allocates memory (e.g. through a + pointer-to-implementation pattern), then you will have to implement + custom copy semantics. - pattern = QRegularExpression::anchoredPattern(pattern); - QRegularExpression(pattern).match(source).hasMatch(); // returns false - \code - - \section3 Minimal matching + \section1 Serialization classes - \c QRegExp::setMinimal() implemented minimal matching by simply reversing - the greediness of the quantifiers (\c QRegExp did not support lazy - quantifiers, like *?, +?, etc.). QRegularExpression instead does support - greedy, lazy and possessive quantifiers. The \l - {QRegularExpression::InvertedGreedinessOption} pattern option can be useful - to emulate the effects of \c QRegExp::setMinimal(): if enabled, it inverts - the greediness of quantifiers (greedy ones become lazy and vice versa). + In Qt 6, QJsonDocument methods for converting it to/from Qt's legacy + JSON binary format were removed in favor of the standardized CBOR format. + Qt JSON types can be converted to Qt CBOR types, which can in turn be + serialized into the CBOR binary format and vice versa. See, for example, + \l QCborValue::fromJsonValue() and \l QCborValue::toJsonValue(). - \section3 Different pattern syntax + If you still need to use the binary JSON format, you can use the + replacements provided in the Qt5Compat module. They can be found in the + \l QBinaryJson namespace. See \l {Using the Qt5Compat module} to find out + how to use the module in your application. - Porting a regular expression from \c QRegExp to \l QRegularExpression may - require changes to the pattern itself. Therefore it is recommended to check - the pattern used with the \l {QRegularExpression::isValid} method. This is - especially important for user provided pattern or pattern not controlled by - the developer. + \section1 Other classes - In other cases, a pattern ported from \c QRegExp to \l QRegularExpression may - silently change semantics. Therefore, it is necessary to review the patterns - used. The most notable cases of silent incompatibility are: + In Qt 5, QCoreApplication::quit() was equivalent to calling + \l{QCoreApplication::exit()}. This just exited the main event loop. - \list - \li Curly braces are needed in order to use a hexadecimal escape like \c - {\xHHHH} with more than 2 digits. A pattern like \c {\x2022} needs - to be ported to \c {\x{2022}}, or it will match a space \c {(0x20)} - followed by the string \c {"22"}. In general, it is highly recommended - to always use curly braces with the \c {\x} escape, no matter the - amount of digits specified. - - \li A \c{0-to-n} quantification like \c {{,n}} needs to be ported to - \c {{0,n}} to preserve semantics. Otherwise, a pattern such as - \c {\d{,3}} would actually match a digit followed by the exact - string \c {"{,3}"}. - \endlist + In Qt 6, the method will instead try to close all top-level windows by posting + a close event. The windows are free to cancel the shutdown process by + ignoring the event. - \section3 Partial Matching + Call QCoreApplication::exit() to keep the non-conditional behavior. - When using \c QRegExp::exactMatch(), if an exact match was not found, one - could still find out how much of the subject string was matched by the - regular expression by calling \c QRegExp::matchedLength(). If the returned - length was equal to the subject string's length, then one could conclude - that a partial match was found. - \l QRegularExpression supports partial matching explicitly by means of the - appropriate \l {QRegularExpression::MatchType}. + QLibraryInfo::location() and QLibraryInfo::Location were deprecated due to inconsistent + naming. Use the new API QLibraryInfo::path() and QLibraryInfo::LibraryPath instead. - \section3 Global matching + \section1 Qt State Machine Framework - Due to limitations of the \c QRegExp API it was impossible to implement - global matching correctly (that is, like Perl does). In particular, patterns - that can match zero characters (like "a*") are problematic. \l - {QRegularExpression::wildcardToRegularExpression} implements Perl global - match correctly, and the returned iterator can be used to examine each - result. + \l {Qt State Machine} was moved into the Qt SCXML module (soon to be renamed to Qt + State Machines) and therefore it is no longer part of Qt Core. There were very few + cross dependencies inside Qt Core which ultimately led to this decision. - \section3 Unicode properties support + \section1 Using the Qt5Compat module - When using \c QRegExp, character classes such as {\w}, {\d}, etc. match - characters with the corresponding Unicode property: for instance, {\d} - matches any character with the Unicode Nd (decimal digit) property. Those - character classes only match ASCII characters by default. When using \l - QRegularExpression: for instance, {\d} matches exactly a character in the - 0-9 ASCII range. It is possible to change this behavior by using the \l - {QRegularExpression::UseUnicodePropertiesOption} - pattern option. + To use the \l {Qt 5 Core Compatibility APIs}{Qt5Compat} module, you need + to build with its headers in your include path and link against its library. + If you are using \l qmake, add the following to your \c .pro file: - \section2 QRegExp - - In Qt6 \l QRegExp got removed from Qt Core. If your application cannot be - ported right now, \c QRegExp still exists in Qt5Compat to keep these - code-bases working. If you want to use \c QRegExp 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: + If you build your application or library using \l {Build with CMake}{cmake}, + add the following to your \c CMakeList.txt: \code PUBLIC_LIBRARIES Qt::Core5Compat |