diff options
Diffstat (limited to 'src/corelib/doc')
49 files changed, 899 insertions, 394 deletions
diff --git a/src/corelib/doc/snippets/code/doc_src_containers.cpp b/src/corelib/doc/snippets/code/doc_src_containers.cpp index 51d369d1d5..680a099f68 100644 --- a/src/corelib/doc/snippets/code/doc_src_containers.cpp +++ b/src/corelib/doc/snippets/code/doc_src_containers.cpp @@ -16,10 +16,30 @@ private: }; //! [0] +//! [range_for] +QList<QString> list = {"A", "B", "C", "D"}; +for (const auto &item : list) { + ... +} +//! [range_for] + +//! [range_for_as_const] +QList<QString> list = {"A", "B", "C", "D"}; +for (const auto &item : std::as_const(list)) { + ... +} +//! [range_for_as_const] + +//! [index] +QList<QString> list = {"A", "B", "C", "D"}; +for (qsizetype i = 0; i < list.size(); ++i) { + const auto &item = list.at(i); + ... +} +//! [index] //! [1] -QList<QString> list; -list << "A" << "B" << "C" << "D"; +QList<QString> list = {"A", "B", "C", "D"}; QListIterator<QString> i(list); while (i.hasNext()) @@ -71,11 +91,12 @@ while (i.hasNext()) //! [7] -QMap<QString, QString> map; -map.insert("Paris", "France"); -map.insert("Guatemala City", "Guatemala"); -map.insert("Mexico City", "Mexico"); -map.insert("Moscow", "Russia"); +QMap<QString, QString> map = { + {"Paris", "France"}, + {"Guatemala City", "Guatemala"}, + {"Mexico City", "Mexico"}, + {"Moscow", "Russia"} +}; ... QMutableMapIterator<QString, QString> i(map); @@ -106,28 +127,23 @@ while (i.findNext(widget)) //! [10] -QList<QString> list; -list << "A" << "B" << "C" << "D"; +QList<QString> list = {"A", "B", "C", "D"}; -QList<QString>::iterator i; -for (i = list.begin(); i != list.end(); ++i) +for (auto i = list.begin(), end = list.end(); i != end; ++i) *i = (*i).toLower(); //! [10] //! [11] -QList<QString> list; -list << "A" << "B" << "C" << "D"; +QList<QString> list = {"A", "B", "C", "D"}; -QList<QString>::reverse_iterator i; -for (i = list.rbegin(); i != list.rend(); ++i) +for (auto i = list.rbegin(), rend = list.rend(); i != rend; ++i) *i = i->toLower(); //! [11] //! [12] -QList<QString>::const_iterator i; -for (i = list.constBegin(); i != list.constEnd(); ++i) +for (auto i = list.cbegin(), end = list.cend(); i != end; ++i) qDebug() << *i; //! [12] @@ -135,8 +151,7 @@ for (i = list.constBegin(); i != list.constEnd(); ++i) //! [13] QMap<int, int> map; ... -QMap<int, int>::const_iterator i; -for (i = map.constBegin(); i != map.constEnd(); ++i) +for (auto i = map.cbegin(), end = map.cend(); i != end; ++i) qDebug() << i.key() << ':' << i.value(); //! [13] @@ -144,13 +159,11 @@ for (i = map.constBegin(); i != map.constEnd(); ++i) //! [14] // RIGHT const QList<int> sizes = splitter->sizes(); -QList<int>::const_iterator i; -for (i = sizes.begin(); i != sizes.end(); ++i) +for (auto i = sizes.begin(), end = sizes.end(); i != end; ++i) ... // WRONG -QList<int>::const_iterator i; -for (i = splitter->sizes().begin(); +for (auto i = splitter->sizes().begin(); i != splitter->sizes().end(); ++i) ... //! [14] @@ -234,9 +247,9 @@ target_compile_definitions(my_app PRIVATE QT_NO_KEYWORDS) QString onlyLetters(const QString &in) { QString out; - for (int j = 0; j < in.size(); ++j) { - if (in[j].isLetter()) - out += in[j]; + for (qsizetype j = 0; j < in.size(); ++j) { + if (in.at(j).isLetter()) + out += in.at(j); } return out; } @@ -273,15 +286,15 @@ int j = *i; // Undefined behavior! //! [24] //! [25] -QList<int> list { 1, 2, 3, 4, 4, 5 }; -QSet<int> set(list.begin(), list.end()); +QList<int> list = {1, 2, 3, 4, 4, 5}; +QSet<int> set(list.cbegin(), list.cend()); /* Will generate a QSet containing 1, 2, 3, 4, 5. */ //! [25] //! [26] -QList<int> list { 2, 3, 1 }; +QList<int> list = {2, 3, 1}; std::sort(list.begin(), list.end()); /* diff --git a/src/corelib/doc/snippets/code/doc_src_qplugin.pro b/src/corelib/doc/snippets/code/doc_src_qplugin.pro deleted file mode 100644 index 52fb9e3163..0000000000 --- a/src/corelib/doc/snippets/code/doc_src_qplugin.pro +++ /dev/null @@ -1,4 +0,0 @@ -#! [3] -TEMPLATE = app -QTPLUGIN += qjpeg qgif # image formats -#! [3] diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp index e50581a2c8..f8b74cd542 100644 --- a/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp @@ -3,10 +3,94 @@ //! [0] - QPropertyAnimation *animation = new QPropertyAnimation(myWidget, "geometry"); - animation->setDuration(10000); - animation->setStartValue(QRect(0, 0, 100, 30)); - animation->setEndValue(QRect(250, 250, 100, 30)); +#include <QApplication> +#include <QPushButton> +#include <QPropertyAnimation> +//! [1] +class MyButtonWidget : public QWidget +{ +public: + MyButtonWidget(QWidget *parent = nullptr); +}; - animation->start(); +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *button = new QPushButton(tr("Animated Button"), this); + QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this); + anim->setDuration(10000); + anim->setStartValue(QPoint(0, 0)); + anim->setEndValue(QPoint(100, 250)); + anim->start(); +} + +int main(int argc, char *argv[]) +{ + QApplication a(argc, argv); + MyButtonWidget buttonAnimWidget; + buttonAnimWidget.resize(QSize(800, 600)); + buttonAnimWidget.show(); + return a.exec(); +} +//! [1] //! [0] + + +//! [easing-curve] +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *button = new QPushButton(tr("Animated Button"), this); + QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this); + anim->setDuration(10000); + anim->setStartValue(QPoint(0, 0)); + anim->setEndValue(QPoint(100, 250)); + anim->setEasingCurve(QEasingCurve::OutBounce); + anim->start(); +} +//! [easing-curve] + + +//! [animation-group1] +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *bonnie = new QPushButton(tr("Bonnie"), this); + QPushButton *clyde = new QPushButton(tr("Clyde"), this); + + QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "pos", this); + anim1->setDuration(3000); + anim1->setStartValue(QPoint(0, 0)); + anim1->setEndValue(QPoint(100, 250)); + + QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "pos", this); + anim2->setDuration(3000); + anim2->setStartValue(QPoint(100, 250)); + anim2->setEndValue(QPoint(500, 500)); + + QParallelAnimationGroup *parallelAnim = new QParallelAnimationGroup; + parallelAnim->addAnimation(anim1); + parallelAnim->addAnimation(anim2); + parallelAnim->start(); +} +//! [animation-group1] + +//! [animation-group2] +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *bonnie = new QPushButton(tr("Bonnie"), this); + QPushButton *clyde = new QPushButton(tr("Clyde"), this); + + QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "pos", this); + anim1->setDuration(3000); + anim1->setStartValue(QPoint(0, 0)); + anim1->setEndValue(QPoint(100, 250)); + + QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "pos", this); + anim2->setDuration(3000); + anim2->setStartValue(QPoint(0, 0)); + anim2->setEndValue(QPoint(200, 250)); + + QSequentialAnimationGroup *sequenceAnim = new QSequentialAnimationGroup; + sequenceAnim->addAnimation(anim1); + sequenceAnim->addAnimation(anim2); + sequenceAnim->start(); +} +//! [animation-group2] diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp index ff5f48b914..1786408c29 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp @@ -708,7 +708,7 @@ bool readConfiguration(const QFile &file) QString s = ...; for (QChar ch : s) // detaches 's' (performs a deep-copy if 's' was shared) process(ch); - for (QChar ch : qAsConst(s)) // ok, no detach attempt + for (QChar ch : std::as_const(s)) // ok, no detach attempt process(ch); //! [as-const-0] @@ -724,12 +724,12 @@ bool readConfiguration(const QFile &file) //! [as-const-2] //! [as-const-3] - for (QChar ch : qAsConst(funcReturningQString())) + for (QChar ch : std::as_const(funcReturningQString())) process(ch); // ERROR: ch is copied from deleted memory //! [as-const-3] //! [as-const-4] - for (QChar ch : qAsConst(funcReturningQString())) + for (QChar ch : std::as_const(funcReturningQString())) process(ch); // ERROR: ch is copied from deleted memory //! [as-const-4] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp index 62ecc58a80..f002ea6fd5 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp @@ -1,6 +1,14 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +//! [constructor-url-reference] +QUrl url("example.com"); +//! [constructor-url-reference] + +//! [constructor-url] +QUrl url("https://example.com"); +//! [constructor-url] + //! [0] QUrl url("http://www.example.com/List of holidays.xml"); // url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml" diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp index b66951357d..a213ccbca6 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp @@ -35,12 +35,12 @@ MyStruct s2 = var.value<MyStruct>(); //! [3] -int id = QMetaType::type("MyClass"); -if (id != QMetaType::UnknownType) { - void *myClassPtr = QMetaType::create(id); +QMetaType type = QMetaType::fromName("MyClass"); +if (type.isValid()) { + void *myClassPtr = type.create(); ... - QMetaType::destroy(id, myClassPtr); - myClassPtr = 0; + type.destroy(myClassPtr); + myClassPtr = nullptr; } //! [3] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qproperty.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qproperty.cpp index f4cc826e6f..c2b55c9684 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qproperty.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qproperty.cpp @@ -144,7 +144,7 @@ public: Q_D(MyClass); d->clients.push_back(c); // notify that the value could have changed - d->hasClientsData.markDirty(); + d->hasClientsData.notify(); } private: Q_DECLARE_PRIVATE(MyClass) diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp index 7dfd17a1f1..5edcaae755 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp @@ -8,7 +8,7 @@ int main(int argc, char *argv[]) { QApplication app(argc, argv); - QTimer::singleShot(600000, &app, SLOT(quit())); + QTimer::singleShot(600000, &app, QCoreApplication::quit); ... return app.exec(); } diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp index e56cb4cdc7..b5d56054c6 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp @@ -30,6 +30,9 @@ if (str == QString("auto") || str == QString("extern") } //! [4] +//! [4bis] +str.append("Hello ").append("World"); +//! [4bis] //! [5] if (str == "auto"_L1 diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp index 6b04d23b97..10e6eb6276 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp @@ -16,7 +16,7 @@ QStringIterator i(string); // implicitly converted to QStringView //! [1] while (i.hasNext()) - uint c = i.next(); + char32_t c = i.next(); //! [1] } diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp index f1be49c1d4..b7e56c5ec3 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp @@ -297,11 +297,11 @@ inline size_t qHash(const std::unordered_set<int> &key, size_t seed = 0) //! [31] //! [32] -size_t qHash(K key); -size_t qHash(const K &key); - size_t qHash(K key, size_t seed); size_t qHash(const K &key, size_t seed); + +size_t qHash(K key); // deprecated, do not use +size_t qHash(const K &key); // deprecated, do not use //! [32] //! [33] diff --git a/src/corelib/doc/snippets/qstringlist/main.cpp b/src/corelib/doc/snippets/qstringlist/main.cpp index fa3540d8ce..d2175aafb5 100644 --- a/src/corelib/doc/snippets/qstringlist/main.cpp +++ b/src/corelib/doc/snippets/qstringlist/main.cpp @@ -22,24 +22,6 @@ Widget::Widget(QWidget *parent) fonts << "Courier" << "Verdana"; //! [0b] -//! [1] - for (int i = 0; i < fonts.size(); ++i) - cout << fonts.at(i).toLocal8Bit().constData() << Qt::endl; -//! [1] - -//! [2] - QStringListIterator javaStyleIterator(fonts); - while (javaStyleIterator.hasNext()) - cout << javaStyleIterator.next().toLocal8Bit().constData() << Qt::endl; -//! [2] - -//! [3] - QStringList::const_iterator constIterator; - for (constIterator = fonts.constBegin(); constIterator != fonts.constEnd(); - ++constIterator) - cout << (*constIterator).toLocal8Bit().constData() << Qt::endl; -//! [3] - //! [4] QString str = fonts.join(", "); // str == "Arial, Helvetica, Times, Courier" diff --git a/src/corelib/doc/src/animation.qdoc b/src/corelib/doc/src/animation.qdoc index e09300010a..28f88c907a 100644 --- a/src/corelib/doc/src/animation.qdoc +++ b/src/corelib/doc/src/animation.qdoc @@ -22,153 +22,134 @@ \keyword Animation - The animation framework aims to provide an easy way for creating animated - and smooth GUIs. By animating Qt properties, the framework provides great - freedom for animating widgets and other \l{QObject}s. The framework can - also be used with the Graphics View framework. Many of the concepts - available in the animation framework are also available in \l{Qt Quick}, - where it offers a declarative way of defining animations. Much of the - knowledge acquired about the animation framework can be applied to - \l{Qt Quick}. - - In this overview, we explain the basics of its architecture. We - also show examples of the most common techniques that the - framework allows for animating \l{QObject}s and graphics items. + The animation framework provides an easy way to animate your GUI elements. + It enables you to animate a Qt property value of a widget or QObject. + Most of the features offered by the framework are also available in + \l{Qt Quick}, where it's possible to define animations in a declarative way. + + This overview explains the framework's architecture, with examples that + demonstrate the common techniques used for animating QObject and + GUI elements. \tableofcontents - \section1 The Animation Architecture + \section1 The Animation architecture - We will in this section take a high-level look at the animation - framework's architecture and how it is used to animate Qt - properties. The following diagram shows the most important classes - in the animation framework. + The following diagram shows the most important classes provided by the + framework: \image animations-architecture.png - The animation framework foundation consists of the base class - QAbstractAnimation, and its two subclasses QVariantAnimation and - QAnimationGroup. QAbstractAnimation is the ancestor of all - animations. It represents basic properties that are common for all - animations in the framework; notably, the ability to start, stop, - and pause an animation. It is also receives the time change - notifications. - - The animation framework further provides the QPropertyAnimation - class, which inherits QVariantAnimation and performs animation of - a Qt property, which is part of Qt's \l{Meta-Object - System}{meta-object system}. The class performs an interpolation - over the property using an easing curve. So when you want to - animate a value, you can declare it as a property and make your - class a QObject. Note that this gives us great freedom in - animating already existing widgets and other \l{QObject}s. + It includes the QAbstractAnimation class, which provides the + necessary foundation for animations. This class defines the + generic properties for all animations supported by the framework. + For example, the ability to start, stop, and pause an animation. The + class also receives the time change notifications. + + The framework further provides the QVariantAnimation and + QAnimationGroup classes, which build on their base case, QAbstractAnimation. + Next in the hierarchy is QPropertyAnimation, which is derived from + QVariantAnmiation, and it lets you animate a Qt property of a widget or + QObject. The class performs interpolation on the property value using an + easing curve. With these in place, you just need a QObject class with a + Qt property value that you can animate. + + \note It is required that the target object you are animating is a QObject + or its subclass. This is necessary as the animation framework depends on the + \l{Meta-Object System}{meta-object system} for all the information about the + object it is animating. Complex animations can be constructed by building a tree structure - of \l{QAbstractAnimation}s. The tree is built by using - \l{QAnimationGroup}s, which function as containers for other - animations. Note also that the groups are subclasses of - QAbstractAnimation, so groups can themselves contain other groups. + of \l{QAbstractAnimation}s, where the tree is a QAnimationGroup that + contains other animations. These animation groups can also contain + subgroups representing different groups or animations, such as + QParallelAnimationGroup and QSequentialAnimationGroup. - Behind the scenes, the animations are controlled by a global - timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to - all animations that are playing. + Behind the scenes, all animations are controlled by a global + timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} about + all animations that are running. - For detailed descriptions of the classes' function and roles in - the framework, please look up their class descriptions. + For detailed information of these individual classes' and their roles in + the framework, refer to their documentation. - \section1 Classes in the Animation Framework + \section1 Classes offered by the framework - These classes provide a framework for creating both simple and complex - animations. + These classes provide the necessary infrastructure to create both simple and + complex animations. \annotatedlist animation - \section1 Animating Qt Properties + \section1 Animating Qt properties - As mentioned in the previous section, the QPropertyAnimation class can - interpolate over Qt properties. It is often this class that should be used - for animation of values; in fact, its superclass, QVariantAnimation, has an - empty implementation of \l{QVariantAnimation::}{updateCurrentValue()}, and - does not change any value unless we change it ourselves on the + As the QPropertyAnimation class can interpolate on Qt properties, it is + used often. In fact, its superclass---QVariantAnimation---provides an + abstract implementation of \l{QVariantAnimation::}{updateCurrentValue()}, + which does not change any value unless you change it on the \l{QVariantAnimation::valueChanged()}{valueChanged signal}. - A major reason we chose to animate Qt properties is that it - presents us with freedom to animate already existing classes in - the Qt API. Notably, the QWidget class (which we can also embed in - a QGraphicsView) has properties for its bounds, colors, etc. - Let's look at a small example: - - \code - QPushButton button("Animated Button"); - button.show(); + The framework lets you animate the Qt properties of the existing + classes in Qt. For example, the QWidget class---can be embedded in + a QGraphicsView---has properties for its bounds, colors, and so on. + The following example demonstrates how you can animate a QPushButton + widget: - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); + \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 - animation.start(); - \endcode + The example animates the \c pos Qt property of a QPushButton, to move + it from the top--left corner of the screen to the end position (250, 250), + in 10 seconds (10000 milliseconds). - This code will move \c button from the top left corner of the - screen to the position (250, 250) in 10 seconds (10000 milliseconds). - - The example above will do a linear interpolation between the - start and end value. It is also possible to set values - situated between the start and end value. The interpolation - will then go by these points. + It uses the linear interpolation method to control the speed of + animation between the start and end values. Try adding another value + in--between the start and end value to see how they are interpolated. + This time use the QPropertyAnimation::setKeyValueAt function to add + these values: \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - - animation.setKeyValueAt(0, QRect(0, 0, 100, 30)); - animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30)); - animation.setKeyValueAt(1, QRect(0, 0, 100, 30)); - - animation.start(); + ... + anim->setDuration(10000); + anim->setKeyValueAt(0, QPoint(0, 0)); + anim->setKeyValueAt(0.8, QPoint(250, 250)); + anim->setKeyValueAt(1, QPoint(0, 0)); + ... \endcode - In this example, the animation will take the button to (250, 250) - in 8 seconds, and then move it back to its original position in - the remaining 2 seconds. The movement will be linearly - interpolated between these points. + In this example, the animation moves the button to + (250, 250) in 8 seconds, and moves it back to its original position in + the remaining 2 seconds. The button's movement is linear-interpolated + between these points. + + You can also animate a QObject's value that is not declared as a Qt + property, if the value has a setter method. In such cases, derive + a new class from the class that contains the value, and add a Qt property + for that value with the setter. - You also have the possibility to animate values of a QObject - that is not declared as a Qt property. The only requirement is - that this value has a setter. You can then subclass the class - containing the value and declare a property that uses this setter. - Note that each Qt property requires a getter, so you will need to - provide a getter yourself if this is not defined. + \note Each Qt property requires a getter also, so you should provide a + getter if that is not defined. \code class MyGraphicsRectItem : public QObject, public QGraphicsRectItem { Q_OBJECT - Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry) + Q_PROPERTY(QPointF pos READ pos WRITE setPos) }; \endcode - In the above code example, we subclass QGraphicsRectItem and - define a geometry property. We can now animate the widgets - geometry even if QGraphicsRectItem does not provide the geometry - property. + In this example, the \c MyGraphicsRectItem derives from + QGraphicsRectItem and QObject, and defines the \c pos property. You can + animate the item's \c pos even if QGraphicsRectItem does not provide + the \c pos property. - For a general introduction to the Qt property system, see its - \l{Qt's Property System}{overview}. + For a general introduction to the Qt property system, refer to + \l{Qt's Property System}. \section1 Animations and the Graphics View Framework - When you want to animate \l{QGraphicsItem}s, you also use - QPropertyAnimation. However, QGraphicsItem does not inherit QObject. - A good solution is to subclass the graphics item you wish to animate. - This class will then also inherit QObject. - This way, QPropertyAnimation can be used for \l{QGraphicsItem}s. - The example below shows how this is done. Another possibility is - to inherit QGraphicsWidget, which already is a QObject. + QPropertyAnimation can also be used to animate a QGraphicsItem, which does + not inherit QObject. In such cases, you derive a class from the graphics + item that you want to animate. This derived class should also inherit form + QObject to enable using QPropertyAnimation on a QGraphicsItem. The + following example shows how this is done: \code class Pixmap : public QObject, public QGraphicsPixmapItem @@ -176,121 +157,78 @@ Q_OBJECT Q_PROPERTY(QPointF pos READ pos WRITE setPos) ... + } \endcode - As described in the previous section, we need to define - properties that we wish to animate. + \note You can also derive from QGraphicsWidget, which already is a + QObject. - Note that QObject must be the first class inherited as the - meta-object system demands this. + As described in the previous section, you need to define + properties that you want to animate. The derived class must inherit + from QObject first as the meta-object system requires it. - \section1 Easing Curves + \section1 Easing curves - As mentioned, QPropertyAnimation performs an interpolation between - the start and end property value. In addition to adding more key - values to the animation, you can also use an easing curve. Easing - curves describe a function that controls how the speed of the - interpolation between 0 and 1 should be, and are useful if you - want to control the speed of an animation without changing the - path of the interpolation. + A QPropertyAnimation performs linear interpolation + between the start and end property values. In addition to adding more key + values to the animation, you can also choose an easing curve to control the + speed of interpolation between 0 and 1, without changing the + path. - \code - QPushButton button("Animated Button"); - button.show(); - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(3000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); - - animation.setEasingCurve(QEasingCurve::OutBounce); - - animation.start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp easing-curve - Here the animation will follow a curve that makes it bounce like a - ball as if it was dropped from the start to the end position. - QEasingCurve has a large collection of curves for you to choose - from. These are defined by the QEasingCurve::Type enum. If you are - in need of another curve, you can also implement one yourself, and + In this example, the animation follows a curve that makes the + \c button bounce like a ball. QEasingCurve offers a large collection of curves + to choose from the QEasingCurve::Type enum. If you want + to use another curve that is not available, implement one yourself and register it with QEasingCurve. - \omit Drop this for the first Lab release - (Example of custom easing curve (without the actual impl of - the function I expect) - \endomit + \section1 Grouping animations - \section1 Putting Animations Together - - An application will often contain more than one animation. For - instance, you might want to move more than one graphics item + An application often contains more than one animation. For + example, it wants to move more than one graphics item simultaneously or move them in sequence after each other. - The subclasses of QAnimationGroup (QSequentialAnimationGroup and - QParallelAnimationGroup) are containers for other animations so + The subclasses of QAnimationGroup---QSequentialAnimationGroup and + QParallelAnimationGroup---are containers for other animations so that these animations can be animated either in sequence or - parallel. The QAnimationGroup is an example of an animation that - does not animate properties, but it gets notified of time changes - periodically. This enables it to forward those time changes to its - contained animations, and thereby controlling when its animations - are played. - - Let's look at code examples that use both - QSequentialAnimationGroup and QParallelAnimationGroup, starting - off with the latter. - - \code - QPushButton *bonnie = new QPushButton("Bonnie"); - bonnie->show(); + parallel. The QAnimationGroup does not animate properties, but it + gets notified of time changes periodically. This enables it to + forward those time changes to the animation groups, which control when + their animations are played. - QPushButton *clyde = new QPushButton("Clyde"); - clyde->show(); + The two following examples demonstrate the use of both + QSequentialAnimationGroup and QParallelAnimationGroup: - QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry"); - // Set up anim1 - - QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry"); - // Set up anim2 - - QParallelAnimationGroup *group = new QParallelAnimationGroup; - group->addAnimation(anim1); - group->addAnimation(anim2); - - group->start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp animation-group1 A parallel group plays more than one animation at the same time. - Calling its \l{QAbstractAnimation::}{start()} function will start - all animations it governs. - - \code - QPushButton button("Animated Button"); - button.show(); + Its \l{QAbstractAnimation::}{start()} function starts all + animations that are part of the group. - QPropertyAnimation anim1(&button, "geometry"); - anim1.setDuration(3000); - anim1.setStartValue(QRect(0, 0, 100, 30)); - anim1.setEndValue(QRect(500, 500, 100, 30)); + \snippet code/src_corelib_animation_qpropertyanimation.cpp animation-group2 - QPropertyAnimation anim2(&button, "geometry"); - anim2.setDuration(3000); - anim2.setStartValue(QRect(500, 500, 100, 30)); - anim2.setEndValue(QRect(1000, 500, 100, 30)); + As the name suggests, a QSequentialAnimationGroup plays + its animations in sequence. It starts the next animation in + the list after the previous finishes. - QSequentialAnimationGroup group; + A group is an animation itself, so you can add + it to another group. This way, building an animation tree, which define + when the animations are played in relation to each other. - group.addAnimation(&anim1); - group.addAnimation(&anim2); + \section1 Object ownership - group.start(); - \endcode + A QPropertyAnimation should always have a parent that controls + its lifespan. A typical application may include several animations that + are grouped, where the animation group takes ownership of those animations. + An independent QProperyAnimation must be explicitly assigned a parent to + control its lifespan. In the following example, you can see that an + independent QPropertyAnimation has the QApplication instance as its + parent: - As you no doubt have guessed, QSequentialAnimationGroup plays - its animations in sequence. It starts the next animation in - the list after the previous is finished. + \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 - Since an animation group is an animation itself, you can add - it to another group. This way, you can build a tree structure - of animations which specifies when the animations are played - in relation to each other. + \note You can also control the animation's lifespan by choosing a + \l{QAbstractAnimation::DeletionPolicy}{delete policy} while starting it. */ diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc new file mode 100644 index 0000000000..22252bbd88 --- /dev/null +++ b/src/corelib/doc/src/cbor.qdoc @@ -0,0 +1,78 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \group cbor + \title CBOR Support in Qt + \ingroup qt-basic-concepts + \brief An overview of CBOR support in Qt. + + \ingroup frameworks-technologies + + \keyword CBOR + + Qt provides support for dealing with CBOR data. CBOR is a binary format to + store data that has a superset of the types available in JSON, but is more + compact. + + The CBOR support in Qt provides an easy to use C++ API to parse, + modify and save CBOR data. + + More details about the CBOR data format can be found in \l {RFC 7049}. + + \tableofcontents + + \section1 Overview + + CBOR is a format to store structured data. It has three groups of built-in types: + + \list + \li Basic types: integers, floating point, boolean, null, etc. + \li String-like types: strings and byte arrays + \li Containers: arrays and maps + \endlist + + In addition, CBOR can add a "tag" to extend the meaning of the type. The + container types can contain basic types, string-like types and containers. + + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} + + \section1 The CBOR Classes + + \section2 The QCborValue Class + + The QCborValue class represents any CBOR type. It also has a simple API for + reading and writing to QCborStreamReader and QCborStreamWriter objects, as + well as manipulating such objects in memory, with the help of QCborArray + and QCborMap. The CborValue API is simplified from the full CBOR data type + and always represents all integers as \l qint64 and all floating-point as + \c double. This means QCborValue is unable to represent CBOR integer values + outside of the range of \l qint64 (-2^63 to 2^63-1). When creating a CBOR + stream, QCborValue::toCbor() can be configured to attempt to write the + shorter single- and half-precision floating-point representations. + + \section2 The QCborArray Class + + The QCborArray class is used to hold an array of QCborValue objects. A + QCborValue object can contain a QCborArray object. It has functions for + converting to and from QVariantList, QStringList, QJsonArray. + + \section2 The QCborMap Class + + The QCborMap class is used to hold an map of QCborValue objects. A + QCborValue object can contain a QCborMap object. It has functions for + converting to and from QVariantMap, QVariantMap, and QJsonObject, but it + can have keys of any type, not just QString. + + \section2 The QCborStreamReader Class + + The QCborStreamReader class is a low level API for reading CBOR data from a + QIODevice, a QByteArray, or a pointer to memory. It has an API similar to + the QXmlStreamReader class. + + \section2 The QCborStreamWriter Class + + The QCborStreamWriter class is a low level API for writing CBOR data to a + QIODevice or a QByteArray. It has an API similar to the QXmlStreamWriter + class. +*/ diff --git a/src/corelib/doc/src/cmake/cmake-commands.qdoc b/src/corelib/doc/src/cmake/cmake-commands.qdoc index 7e98c16e41..e185bab624 100644 --- a/src/corelib/doc/src/cmake/cmake-commands.qdoc +++ b/src/corelib/doc/src/cmake/cmake-commands.qdoc @@ -4,6 +4,7 @@ /*! \group cmake-commands-qtcore \title CMake Commands in Qt6 Core +\brief Lists CMake commands defined in Qt6::Core. The following CMake commands are defined when Qt6::Core is loaded, for instance with diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index 116e08fef4..64275c35f7 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -10,6 +10,7 @@ /*! \group cmake-variables-qtcore \title CMake Variables in Qt6 Core +\brief Lists CMake variables defined in Qt6::Core. The following CMake variables are defined when Qt6::Core is loaded, for instance with @@ -22,7 +23,7 @@ find_package(Qt6 REQUIRED COMPONENTS Core) */ */*! -\page cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME.html +\page cmake-variable-android-ndk-host-system-name.html \ingroup cmake-variables-qtcore \title ANDROID_NDK_HOST_SYSTEM_NAME @@ -41,7 +42,7 @@ part of the deployment settings for a target. */ /*! -\page cmake-variable-ANDROID_SDK_ROOT.html +\page cmake-variable-android-sdk-root.html \ingroup cmake-variables-qtcore \title ANDROID_SDK_ROOT @@ -60,7 +61,7 @@ It is written out as part of the deployment settings for a target. */ /*! -\page cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS.html +\page cmake-variable-qt-android-application-arguments.html \ingroup cmake-variables-qtcore \title QT_ANDROID_APPLICATION_ARGUMENTS @@ -79,7 +80,88 @@ out as part of the deployment settings for a target. */ /*! -\page cmake-variable-QT_ANDROID_BUILD_ALL_ABIS.html +\page cmake_variable-qt-android-multi-abi-forward-vars +\ingroup cmake-variables-qtcore + +\title QT_ANDROID_MULTI_ABI_FORWARD_VARS +\target cmake-variable-QT_ANDROID_MULTI_ABI_FORWARD_VARS + +\summary {Allows to share CMake variables in multi-ABI builds} + +\cmakevariablesince 6.4.2 +\preliminarycmakevariable +\cmakevariableandroidonly + +The \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable allows specifying the list of +CMake variables that need to be forwarded from the main ABI project to +ABI-specific subprojects. Due to the specifics of the Multi-ABI project build +process, there is no generic way to forward the CMake cache variables +that are specified either in the command line or in another similar way. + +A typical use case for the variable is propagating CMake cache variables +specified in the command line. For example, a project has two variables +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} that affect the +project configuration: +\badcode +cmake_minimum_required(VERSION 3.18) + +project(MyProject LANGUAGES CXX) + +find_package(Qt6 REQUIRED COMPONENTS Core) + +qt_add_executable(MyApp main.cpp) + +if(PROJECT_WIDE_VARIABLE1) + target_sources(MyApp PRIVATE sourcefile1.cpp) +endif() +if(PROJECT_WIDE_VARIABLE2) + target_sources(MyApp PRIVATE sourcefile2.cpp) +endif() +\endcode + +The above contents of \c{CMakeLists.txt} enable you to control how +\c{MyApp} is built by setting the corresponding CMake variables from the +command line: +\badcode +qt-cmake -S<source directory> -B<build directory> \ + -DPROJECT_WIDE_VARIABLE1=ON \ + -DPROJECT_WIDE_VARIABLE2=ON \ + -DQT_ANDROID_MULTI_ABI_FORWARD_VARS="PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2" +\endcode + +When configuring the application for desktop, \c{PROJECT_WIDE_VARIABLE1} and +\c{PROJECT_WIDE_VARIABLE2} are visible in CMake listings and scripts as global +cache variables. This doesn't work for Android Multi-ABI builds because +ABI-specific subprojects do not inherit the cache variables from the main-ABI +project. This issue can be solved by passing the list of required variables to +the \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable, so both +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} values will be +propagated to the ABI-specific builds. + +The variable can be also defined in the project's CMakeLists.txt: +\badcode +... +qt_add_executable(MyApp main.cpp) +... +if(ANDROID) + set(QT_ANDROID_MULTI_ABI_FORWARD_VARS "PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2") +endif() +... +\endcode + +Setting the variable in this way allows you to have a predefined set of +variables that will always be forwarded to abi-specific projects. + +\note The forwarding is done in the target finalizer, which is implicitly +called when \l{qt6_add_executable}{qt_add_executable()} is used. The +finalization occurs automatically when using CMake 3.19 or later. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} +*/ + +/*! +\page cmake-variable-qt-android-build-all-abis.html \ingroup cmake-variables-qtcore \title QT_ANDROID_BUILD_ALL_ABIS @@ -98,11 +180,11 @@ supplied by the Qt installer, with the corresponding naming of the directories. The typical directory structure looks as below: \badcode /path/to/Qt/6.x.x -Â Â Â android_armv7 -Â Â Â android_arm64_v8a -Â Â Â android_x86 -Â Â Â android_x86_64 -Â Â Â ... + android_armv7 + android_arm64_v8a + android_x86 + android_x86_64 + ... \endcode The auto-detected paths can be customized using one of \c{QT_PATH_ANDROID_ABI_<ABI>} variables. @@ -112,7 +194,7 @@ The variable is set to FALSE by default. */ /*! -\page cmake-variable-QT_ANDROID_ABIS.html +\page cmake-variable-qt-android-abis.html \ingroup cmake-variables-qtcore \title QT_ANDROID_ABIS @@ -137,7 +219,7 @@ QT_ANDROID_ABIS logic. */ /*! -\page cmake-variable-QT_PATH_ANDROID_ABI.html +\page cmake-variable-qt-path-android-abi.html \ingroup cmake-variables-qtcore \title QT_PATH_ANDROID_ABI_<ABI> @@ -156,7 +238,32 @@ Each variable can be used to specify the path to Qt for Android for the correspo */ /*! -\page cmake-variable-QT_ANDROID_SIGN_APK.html +\page cmake-variable-qt-android-sign-aab.html +\ingroup cmake-variables-qtcore + +\title QT_ANDROID_SIGN_AAB +\target cmake-variable-QT_ANDROID_SIGN_AAB + +\summary {Sign the .aab package with the specified keystore, alias and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +Sign the resulting package. The path of the keystore file, the alias of the key and passwords +have to be specified by additional environment variables: +\badcode + QT_ANDROID_KEYSTORE_PATH + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +Mentioned variables are used internally by \l{androiddeployqt}. + +\sa{androiddeployqt} +*/ + +/*! +\page cmake-variable-qt-android-sign-apk.html \ingroup cmake-variables-qtcore \title QT_ANDROID_SIGN_APK @@ -181,7 +288,29 @@ Mentioned variables are used internally by \l{androiddeployqt}. */ /*! -\page cmake-variable-QT_HOST_PATH.html +\page cmake-variable-qt-no-collect-build-tree-apk-deps.html +\ingroup cmake-variables-qtcore + +\title QT_NO_COLLECT_BUILD_TREE_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS + +\summary {Prevents collecting of project-built shared library targets during Android deployment.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +During project finalization, the build system collects the locations of +all built shared library targets in the project. +These locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +Set \c QT_NO_COLLECT_BUILD_TREE_APK_DEPS to \c TRUE to disable this behavior. + +\sa {qt6_finalize_project}{qt_finalize_project()} +*/ + +/*! +\page cmake-variable-qt-host-path.html \ingroup cmake-variables-qtcore \title QT_HOST_PATH @@ -190,7 +319,6 @@ Mentioned variables are used internally by \l{androiddeployqt}. \summary {Location of the host Qt installation when cross-compiling.} \cmakevariablesince 6.0 -\preliminarycmakevariable When cross-compiling, this must be set to the install location of Qt for the host platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, @@ -198,7 +326,7 @@ platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, */ /*! -\page cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID.html +\page cmake-variable-qt-no-set-xcode-development-team-id.html \ingroup cmake-variables-qtcore \title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID @@ -215,7 +343,7 @@ Set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to true if you want to prevent this. */ /*! -\page cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER.html +\page cmake-variable-qt-no-set-xcode-bundle-identifier.html \ingroup cmake-variables-qtcore \title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER @@ -233,7 +361,7 @@ Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. */ /*! -\page cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT.html +\page cmake-variable-qt-enable-verbose-deployment.html \ingroup cmake-variables-qtcore \title QT_ENABLE_VERBOSE_DEPLOYMENT @@ -253,7 +381,7 @@ must be set before the first \c{find_package(Qt6)} call to have that effect. */ /*! -\page cmake-variable-QT_DEPLOY_SUPPORT.html +\page cmake-variable-qt-deploy-support.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_SUPPORT @@ -280,7 +408,7 @@ an application, along with its runtime dependencies: */ /*! -\page cmake-variable-QT_NO_STANDARD_PROJECT_SETUP.html +\page cmake-variable-qt-no-standard-project-setup.html \ingroup cmake-variables-qtcore \title QT_NO_STANDARD_PROJECT_SETUP @@ -302,3 +430,22 @@ methods provided by CMake. \sa {qt6_standard_project_setup}{qt_standard_project_setup()} */ + +/*! +\page cmake-variable-qt-ios-launch-screen.html +\ingroup cmake-variables-qtcore + +\title QT_IOS_LAUNCH_SCREEN +\target cmake-variable-QT_IOS_LAUNCH_SCREEN + +\summary {Path to iOS launch screen storyboard used by all targets} + +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableiosonly + +Specifies the path to an iOS launch screen storyboard file that will be used +by all targets within a project. + +\sa {Launch Screens and Launch Images} +*/ diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc index b10de9dc3b..0a0902e0de 100644 --- a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -8,7 +8,7 @@ **/ /*! -\page cmake-variable-QT_DEPLOY_PREFIX.html +\page cmake-variable-qt-deploy-prefix.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_PREFIX @@ -53,7 +53,7 @@ variables. */ /*! -\page cmake-variable-QT_DEPLOY_BIN_DIR.html +\page cmake-variable-qt-deploy-bin-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_BIN_DIR @@ -94,7 +94,7 @@ should not be used for that scenario. */ /*! -\page cmake-variable-QT_DEPLOY_LIB_DIR.html +\page cmake-variable-qt-deploy-lib-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_LIB_DIR @@ -136,7 +136,7 @@ should not be used for that scenario. */ /*! -\page cmake-variable-QT_DEPLOY_PLUGINS_DIR.html +\page cmake-variable-qt-deploy-plugins-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_PLUGINS_DIR @@ -172,7 +172,7 @@ bundle contents. */ /*! -\page cmake-variable-QT_DEPLOY_QML_DIR.html +\page cmake-variable-qt-deploy-qml-dir.html \ingroup cmake-variables-qtcore \title QT_DEPLOY_QML_DIR diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc index bbb948aec2..fbb75c1830 100644 --- a/src/corelib/doc/src/cmake/cmake-properties.qdoc +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -4,6 +4,7 @@ /*! \group cmake-target-properties-qtcore \title CMake Target Properties in Qt6 Core +\brief Lists CMake target properties known to Qt6::Core. \l{CMake Commands in Qt6 Core}{CMake Commands} know about the following CMake target properties: @@ -12,7 +13,7 @@ target properties: */ /*! -\page cmake-target-property-QT_ANDROID_DEPLOYMENT_DEPENDENCIES.html +\page cmake-target-property-qt-android-deployment-dependencies.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -43,7 +44,7 @@ is listed before its dependencies, it will fail to load on some devices. */ /*! -\page cmake-target-property-QT_ANDROID_EXTRA_LIBS.html +\page cmake-target-property-qt-android-extra-libs.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -65,7 +66,7 @@ to enable OpenSSL in your application. For more information, see */ /*! -\page cmake-target-property-QT_ANDROID_EXTRA_PLUGINS.html +\page cmake-target-property-qt-android-extra-plugins.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -96,7 +97,7 @@ mangling is applied to the plugin library. */ /*! -\page cmake-target-property-QT_ANDROID_MIN_SDK_VERSION.html +\page cmake-target-property-qt-android-min-sdk-version.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -115,7 +116,7 @@ Specifies the minimum Android API level for the target. */ /*! -\page cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR.html +\page cmake-target-property-qt-android-package-source-dir.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -148,7 +149,7 @@ then place this directly into the directory specified by this variable. */ /*! -\page cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION.html +\page cmake-target-property-qt-android-target-sdk-version.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -167,7 +168,27 @@ Specifies the target Android API level for the target. */ /*! -\page cmake-target-property-QT_ANDROID_VERSION_CODE.html +\page cmake-target-property-qt-android-sdk-build-tools-revision.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_ANDROID_SDK_BUILD_TOOLS_REVISION +\target cmake-target-property-QT_ANDROID_SDK_BUILD_TOOLS_REVISION + +\summary {Revision of Android build tools to use.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the Android SDK build tools revision to use. If this is not set then +CMake will attempt to use the latest installed version. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-version-code.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -189,7 +210,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. */ /*! -\page cmake-target-property-QT_ANDROID_VERSION_NAME.html +\page cmake-target-property-qt-android-version-name.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -211,7 +232,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. */ /*! -\page cmake-target-property-QT_ANDROID_ABIS.html +\page cmake-target-property-qt-android-abis.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -234,7 +255,7 @@ The property only affects targets created with */ /*! -\page cmake-target-property-QT_QML_ROOT_PATH.html +\page cmake-target-property-qt-qml-root-path.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -255,7 +276,7 @@ will be used instead. */ /*! -\page cmake-target-property-QT_QML_IMPORT_PATH.html +\page cmake-target-property-qt-qml-import-path.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -277,7 +298,7 @@ For application-specific QML imports, use */ /*! -\page cmake-target-property-QT_ANDROID_DEPLOYMENT_SETTINGS_FILE.html +\page cmake-target-property-qt-android-deployment-settings-file.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -297,7 +318,7 @@ and overwritten by that command. */ /*! -\page cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX.html +\page cmake-target-property-qt-android-system-libs-prefix.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -314,7 +335,7 @@ when those libraries are installed outside app's native (JNI) library directory. */ /*! -\page cmake-target-property-QT_ANDROID_NO_DEPLOY_QT_LIBS.html +\page cmake-target-property-qt-android-no-deploy-qt-libs.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -336,7 +357,7 @@ instead. */ /*! -\page cmake-target-property-qt_no_entrypoint.html +\page cmake-target-property-qt-no-entrypoint.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -355,7 +376,7 @@ On targets that must provide their own entry point, set the property \c qt_no_en */ /*! -\page cmake-target-property-qt_resource_prefix.html +\page cmake-target-property-qt-resource-prefix.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -375,6 +396,7 @@ resource prefix. /*! \group cmake-source-file-properties-qtcore \title CMake Source File Properties in Qt6 Core +\brief Lists CMake file properties used in Qt6::Core. \l{CMake Commands in Qt6 Core}{CMake Commands} know about the following CMake source file properties: @@ -383,7 +405,7 @@ source file properties: */ /*! -\page cmake-source-file-property-QT_RESOURCE_ALIAS.html +\page cmake-source-file-property-qt-resource-alias.html \ingroup cmake-source-file-properties-qtcore \title QT_RESOURCE_ALIAS @@ -401,7 +423,7 @@ the property value overrides the runtime path where the resource file is found. */ /*! -\page cmake-target-property-QT_WASM_PTHREAD_POOL_SIZE.html +\page cmake-target-property-qt-wasm-pthread-pool-size.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -425,7 +447,7 @@ For more information, see \l{https://emscripten.org/docs/porting/pthreads.html}{ */ /*! -\page cmake-target-property-QT_WASM_INITIAL_MEMORY.html +\page cmake-target-property-qt-wasm-initial-memory.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore @@ -445,3 +467,22 @@ QT_WASM_INITIAL_MEMORY must be a multiple of 65536 bytes. For more information, see \l{https://github.com/emscripten-core/emscripten/blob/main/src/settings.js}{Emscripten compiler settings}. */ + +/*! +\page cmake-target-property-qt-ios-launch-screen.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_IOS_LAUNCH_SCREEN +\target cmake-target-property-QT_IOS_LAUNCH_SCREEN + +\summary {Path to iOS launch screen storyboard} + +\cmakepropertysince 6.4 +\preliminarycmakeproperty +\cmakepropertyiosonly + +Specifies the path to an iOS launch screen storyboard file. + +\sa {Launch Screens and Launch Images} +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc index 5ae7b9728b..72a00e6eef 100644 --- a/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_bigresources.html +\page qt-add-bigresources.html \ingroup cmake-commands-qtcore \title qt_add_big_resources diff --git a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc index a247b6d7c0..71ee8b894e 100644 --- a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_binary_resources.html +\page qt-add-binary-resources.html \ingroup cmake-commands-qtcore \title qt_add_binary_resources diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc index a09ecc8dfd..c68366cdf8 100644 --- a/src/corelib/doc/src/cmake/qt_add_executable.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_executable.html +\page qt-add-executable.html \ingroup cmake-commands-qtcore \title qt_add_executable @@ -60,25 +60,34 @@ for you as a convenience. After a target is created, further processing or \e{finalization} steps are commonly needed. The steps to perform depend on the platform and on various -properties of the target. The finalization processing is implemented by the -\l{qt6_finalize_target}{qt_finalize_target()} command. You might need to also -call the \l{qt6_finalize_project}{qt_finalize_project()} command at the end -of top-level CMakeLists.txt to correctly resolve the dependencies between -project targets. - -Finalization can occur either as part of this call or be deferred to sometime -after this command returns (but it should still be in the same directory scope). -When using CMake 3.19 or later, finalization is automatically deferred to the +properties of the target. + +The finalization processing is implemented by two commands: +\l{qt6_finalize_target}{qt_finalize_target()} and +\l{qt6_finalize_project}{qt_finalize_project()}. + +Target finalization can occur either as part of calling \c{qt_add_executable} +or be deferred to sometime after this command returns (but it should still be in +the same directory scope). + +When using CMake 3.19 or later, target finalization is automatically deferred to the end of the current directory scope. This gives the caller an opportunity to modify properties of the created target before it is finalized. When using CMake versions earlier than 3.19, automatic deferral isn't supported. In that -case, finalization is performed immediately before this command returns. +case, target finalization is performed immediately before this command returns. Regardless of the CMake version, the \c{MANUAL_FINALIZATION} keyword can be given to indicate that you will explicitly call \l{qt6_finalize_target}{qt_finalize_target()} yourself instead at some later time. In general, \c MANUAL_FINALIZATION should not be needed unless the project has to support CMake 3.18 or earlier. +Project finalization occurs automatically when using CMake 3.19 or later. +When using an older CMake version, you should call +\l{qt6_finalize_project}{qt_finalize_project()} manually, at the end +of the root \c CMakeLists.txt file. +This is especially important when targeting Android, to collect dependencies +between project targets for deployment purposes. + \sa {qt6_finalize_target}{qt_finalize_target()}, {qt6_set_finalizer_mode}{qt_set_finalizer_mode()}, {qt6_add_library}{qt_add_library()}, diff --git a/src/corelib/doc/src/cmake/qt_add_library.qdoc b/src/corelib/doc/src/cmake/qt_add_library.qdoc index 52b85d0476..ae1da18eee 100644 --- a/src/corelib/doc/src/cmake/qt_add_library.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_library.html +\page qt-add-library.html \ingroup cmake-commands-qtcore \title qt_add_library diff --git a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc index 89a68dbee2..b69d30d62a 100644 --- a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_plugin.html +\page qt-add-plugin.html \ingroup cmake-commands-qtcore \title qt_add_plugin diff --git a/src/corelib/doc/src/cmake/qt_add_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_resources.qdoc index 7de9b94854..2bca258980 100644 --- a/src/corelib/doc/src/cmake/qt_add_resources.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_resources.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_add_resources.html +\page qt-add-resources.html \ingroup cmake-commands-qtcore \title qt_add_resources diff --git a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc index 8219380bd5..617baa0109 100644 --- a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc +++ b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_allow_non_utf8_sources.html +\page qt-allow-non-utf8-sources.html \ingroup cmake-commands-qtcore \title qt_allow_non_utf8_sources diff --git a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc index 7818596c76..747849eabb 100644 --- a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_android_add_apk_target.html +\page qt-android-add-apk-target.html \ingroup cmake-commands-qtcore \title qt_android_add_apk_target diff --git a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc index 5451a6727c..4d4585693d 100644 --- a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_android_apply_arch_suffix.html +\page qt-android-apply-arch-suffix.html \ingroup cmake-commands-qtcore \title qt_android_apply_arch_suffix diff --git a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc index 4df3a32101..a717c80e7c 100644 --- a/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc +++ b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_android_generate_deployment_settings.html +\page qt-android-generate-deployment-settings.html \ingroup cmake-commands-qtcore \title qt_android_generate_deployment_settings diff --git a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc index 4f2b638835..ca17206925 100644 --- a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc +++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_deploy_qt_conf.html +\page qt-deploy-qt-conf.html \ingroup cmake-commands-qtcore \title qt_deploy_qt_conf diff --git a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc index 6f950b4020..083d8da095 100644 --- a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc +++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_deploy_runtime_dependencies.html +\page qt-deploy-runtime-dependencies.html \ingroup cmake-commands-qtcore \title qt_deploy_runtime_dependencies diff --git a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc index b056afea85..f4ad3c6426 100644 --- a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc +++ b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_disable_unicode_defines.html +\page qt-disable-unicode-defines.html \ingroup cmake-commands-qtcore \title qt_disable_unicode_defines diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc index a430989036..837baa3f0c 100644 --- a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_extract_metatypes.html +\page qt-extract-metatypes.html \ingroup cmake-commands-qtcore \title qt_extract_metatypes diff --git a/src/corelib/doc/src/cmake/qt_finalize_project.qdoc b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc index dc63e66cd6..af7707f116 100644 --- a/src/corelib/doc/src/cmake/qt_finalize_project.qdoc +++ b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc @@ -2,13 +2,13 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_finalize_project.html +\page qt-finalize-project.html \ingroup cmake-commands-qtcore \title qt_finalize_project \target qt6_finalize_project -\summary {Handles various common platform-specific tasks associated with Qt project.} +\summary {Handles various common platform-specific tasks associated with a Qt project.} \preliminarycmakecommand \include cmake-find-package-core.qdocinc @@ -26,13 +26,17 @@ qt_finalize_project() \section1 Description Some targets that are created using Qt commands require additional actions -at the end of CMake configuring phase. Depending on the platform the function -typically walks through the build tree, resolves dependencies between targets -created by the user, and applies extra deployment steps. - -With CMake versions 3.19 and higher, you don't need to call this command since +at the end of CMake configuring phase. +Depending on the platform, the function typically: +\list + \li Walks the build tree. + \li Resolves dependencies. + \li Applies any extra deployment steps. +\endlist + +With CMake version 3.19 or later, you don't need to call this command since it consists of sub-commands that are ordinarily invoked at the end of -\c CMAKE_SOURCE_DIR scope. +\c CMAKE_SOURCE_DIR directory scope processing. \include cmake-android-qt-finalize-project-warning.cmake @@ -44,4 +48,5 @@ function: \snippet cmake-macros/examples.cmake qt_finalize_project_manual +\sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS} */ diff --git a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc index 558e89991f..277c32ea57 100644 --- a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc +++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_finalize_target.html +\page qt-finalize-target.html \ingroup cmake-commands-qtcore \title qt_finalize_target diff --git a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc index b3a3328098..164bc3350b 100644 --- a/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_generate_deploy_app_script.html +\page qt-generate-deploy-app-script.html \ingroup cmake-commands-qtcore \title qt_generate_deploy_app_script diff --git a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc index 4f60ae1ae2..55b6df9e7d 100644 --- a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc +++ b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_generate_moc.html +\page qt-generate-moc.html \ingroup cmake-commands-qtcore \title qt_generate_moc diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc index cea6fc61f5..b9606654b0 100644 --- a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_import_plugins.html +\page qt-import-plugins.html \ingroup cmake-commands-qtcore \title qt_import_plugins diff --git a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc index 476c63ccc0..f44a217544 100644 --- a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc +++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_set_finalizer_mode.html +\page qt-set-finalizer-mode.html \ingroup cmake-commands-qtcore \title qt_set_finalizer_mode diff --git a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc index b94d688e49..837aee304a 100644 --- a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc +++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_standard_project_setup.html +\page qt-standard-project-setup.html \ingroup cmake-commands-qtcore \title qt_standard_project_setup diff --git a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc index 8390b81cd3..c2a916c71c 100644 --- a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc +++ b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_wrap_cpp.html +\page qt-wrap-cpp.html \ingroup cmake-commands-qtcore \title qt_wrap_cpp diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index bed184de15..4a7d5dc1bb 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -39,7 +39,8 @@ \note Since Qt 5.14, range constructors are available for most of the container classes. QMultiMap is a notable exception. Their use is - encouraged in place of the various from/to methods. For example: + encouraged to replace of the various deprecated from/to methods of Qt 5. + For example: \snippet code/doc_src_containers.cpp 25 @@ -191,7 +192,30 @@ the C++ language doesn't specify any initialization; in those cases, Qt's containers automatically initialize the value to 0. - \section1 The Iterator Classes + \section1 Iterating over Containers + + \section2 Range-based for + + Range-based \c for should preferably be used for containers: + + \snippet code/doc_src_containers.cpp range_for + + Note that when using a Qt container in a non-const context, + \l{implicit sharing} may perform an undesired detach of the container. + To prevent this, use \c std::as_const(): + + \snippet code/doc_src_containers.cpp range_for_as_const + + For associative containers, this will loop over the values. + + \section2 Index-based + + For sequential containers that store their items contiguously in memory + (for example, QList), index-based iteration can be used: + + \snippet code/doc_src_containers.cpp index + + \section2 The Iterator Classes Iterators provide a uniform means to access items in a container. Qt's container classes provide two types of iterators: STL-style @@ -200,7 +224,7 @@ from \l{Implicit Sharing}{implicitly shared copies} due to a call to a non-const member function. - \section2 STL-Style Iterators + \section3 STL-Style Iterators STL-style iterators have been available since the release of Qt 2.0. They are compatible with Qt's and STL's \l{generic @@ -262,12 +286,10 @@ In the code snippets so far, we used the unary \c * operator to retrieve the item (of type QString) stored at a certain iterator - position, and we then called QString::toLower() on it. Most C++ - compilers also allow us to write \c{i->toLower()}, but some - don't. + position, and we then called QString::toLower() on it. - For read-only access, you can use const_iterator, \l{QList::constBegin}{constBegin()}, - and \l{QList::constEnd()}{constEnd()}. For example: + For read-only access, you can use const_iterator, \l{QList::cbegin}{cbegin()}, + and \l{QList::cend()}{cend()}. For example: \snippet code/doc_src_containers.cpp 12 @@ -315,7 +337,7 @@ This problem doesn't occur with functions that return a const or non-const reference to a container. - \section3 Implicit sharing iterator problem + \section4 Implicit sharing iterator problem \l{Implicit sharing} has another consequence on STL-style iterators: you should avoid copying a container while @@ -328,33 +350,11 @@ The above example only shows a problem with QList, but the problem exists for all the implicitly shared Qt containers. - \section2 Java-Style Iterators + \section3 Java-Style Iterators \l{java-style-iterators}{Java-Style iterators} were introduced in Qt 4. Their API is modelled on Java's iterator classes. New code should should prefer \l{STL-Style Iterators}. - \section1 Container keywords - - \target foreach - \section2 The foreach Keyword - \l{foreach-keyword}{The foreach keyword} is discouraged, new code should - prefer C++11 range-based loops. - - \target forever - \section2 The forever keyword. - In addition to \c foreach, Qt also provides a \c forever - pseudo-keyword for infinite loops: - - \snippet code/doc_src_containers.cpp 21 - - If you're worried about namespace pollution, you can disable - these macros by adding the following line to your \c .pro file: - - \snippet code/doc_src_containers.cpp 22 - - \note The alternative macros Q_FOREACH and Q_FOREVER remain defined - regardless. - \section1 Qt containers compared with std containers \table @@ -383,7 +383,7 @@ \li Similar to std::queue<T>, inherits from \l{QList}. \row \li \l{QSet}<T> - \li Similar to std::set<T>. Internally, \l{QSet} is implemented with a + \li Similar to std::unordered_set<T>. Internally, \l{QSet} is implemented with a \l{QHash}. \row \li \l{QMap}<Key, T> @@ -393,16 +393,16 @@ \li Similar to std::multimap<T>. \row \li \l{QHash}<Key, T> - \li Most similar to std::map<T>. + \li Most similar to std::unordered_map<T>. \row \li \l{QMultiHash}<Key, T> - \li Most similar to std::multimap<T>. + \li Most similar to std::unordered_multimap<T>. \endtable \section1 Qt containers and std algorithms - You can used Qt containers with functions from \c{#include <algorithm>}. + You can use Qt containers with functions from \c{#include <algorithm>}. \snippet code/doc_src_containers.cpp 26 @@ -410,7 +410,7 @@ Qt includes other template classes that resemble containers in some respects. These classes don't provide iterators and cannot - be used with the \c foreach keyword. + be used with the \l foreach keyword. \list \li QCache<Key, T> provides a cache to store objects of a certain diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index c3e57a9adf..60ea1aa495 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -67,5 +67,6 @@ \li QVector4D \endlist - \sa {JSON Support in Qt} + \sa {JSON Support in Qt}, {CBOR Support in Qt} + */ diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc index 7e8977dbd9..3210d92cc7 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -83,6 +83,36 @@ */ /*! + \externalpage https://developer.android.com/training/data-storage/shared/documents-files + \title Android: Access documents and other files from shared storage +*/ + +/*! + \externalpage https://developer.android.com/reference/androidx/documentfile/provider/DocumentFile#getParentFile() + \title Android: DocumentFile.getParentFile() +*/ + +/*! + \externalpage https://developer.android.com/guide/topics/providers/content-provider-basics#ContentURIs + \title Android: Content URIs +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage#scoped-storage + \title Android: Scoped storage +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage/use-cases + \title Android: storage best practices +*/ + +/*! + \externalpage https://developer.android.com/reference/android/provider/MediaStore + \title Android: MediaStore +*/ + +/*! \externalpage https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html \title GNUInstallDirs */ diff --git a/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc new file mode 100644 index 0000000000..f08086407e --- /dev/null +++ b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc @@ -0,0 +1,13 @@ +On Android, some limitations apply when dealing with +\l {Android: Content URIs}{content URIs}: +\list + \li Access permissions might be needed by prompting the user through the + \l QFileDialog which implements + \l {Access documents and other files from shared storage}{Android's native file picker}. + \li Aim to follow the \l {Android: Scoped storage}{Scoped storage} guidelines, + such as using app specific directories instead of other public external directories. + For more information, also see + \l {Android: storage best practices}{storage best practices}. + \li Due to the design of Qt APIs (e.g. QFile), it's not possible to fully + integrate the latter APIs with Android's \l {Android: MediaStore}{MediaStore} APIs. +\endlist diff --git a/src/corelib/doc/src/io.qdoc b/src/corelib/doc/src/io.qdoc index 80caf9a769..443d324f75 100644 --- a/src/corelib/doc/src/io.qdoc +++ b/src/corelib/doc/src/io.qdoc @@ -10,7 +10,7 @@ network handling. These \l{Qt Core} classes are used to handle input and output to and from - external devices, processes, files etc. as well as manipulating files and + external devices, processes, files etc., as well as manipulating files and directories. */ diff --git a/src/corelib/doc/src/qtcore-index.qdoc b/src/corelib/doc/src/qtcore-index.qdoc index 377e199784..99cc114d64 100644 --- a/src/corelib/doc/src/qtcore-index.qdoc +++ b/src/corelib/doc/src/qtcore-index.qdoc @@ -75,6 +75,7 @@ \list \li \l{The Animation Framework} \li \l{JSON Support in Qt} + \li \l{CBOR Support in Qt} \li \l{How to Create Qt Plugins} \li \l{The Event System} \endlist diff --git a/src/corelib/doc/src/qtcore.qdoc b/src/corelib/doc/src/qtcore.qdoc index 2ef705dd75..a46add1342 100644 --- a/src/corelib/doc/src/qtcore.qdoc +++ b/src/corelib/doc/src/qtcore.qdoc @@ -18,9 +18,17 @@ /*! \module QtCorePrivate \title Qt Core Private C++ Classes - \qtcmakepackage CorePrivate \qtvariable core-private - - \brief Provides private core functionality. \preliminary + \brief Provides private core functionality. + +//! [qtcoreprivate-usage] + When building with CMake, use the following commands to use + private Qt Core APIs: + + \badcode + find_package(Qt6 REQUIRED COMPONENTS Core) + target_link_libraries(mytarget PRIVATE Qt6::CorePrivate) + \endcode +//! [qtcoreprivate-usage] */ diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc new file mode 100644 index 0000000000..dfceed55f2 --- /dev/null +++ b/src/corelib/doc/src/qtserialization.qdoc @@ -0,0 +1,138 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtserialization.html + \title Qt Serialization + \brief Serializations provided by Qt API + + The purpose of serialization is to save the state of an object to be able to + recreate it when needed. It allows you to perform actions like: + + \list + \li Sending the object to a remote application by using a web service + \li Passing the object as a JSON or XML string + \li Saving and restoring user information or sharing it across applications + \endlist + + The Qt API provides support for serialization for several use cases: + + \list + \li \l JSON support in Qt provides an easy to use C++ API to parse, modify + and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form + of binary data encoding that is a superset of JSON. + \li \l QDataStream provides serialization of binary data to a QIODevice + \li \l {Qt XML C++ Classes} provide C++ implementations of the \l XML Streaming + and DOM standards for XML + \li \l CBOR is Qt's implementation for the CBOR serialization format. + \li \l QSettings provides a way of serializing and storing platform independent + application settings. + \endlist + + \section1 Advantages of JSON and CBOR + + When you use \l JSON information is stored in a QJsonObject and a QJsonDocument + takes care to stream values into a QByteArray. + + For example + \code + QJsonObject jobject; + jobject["SensorID"] = m_id; + jobject["AmbientTemperature"] = m_ambientTemperature; + jobject["ObjectTemperature"] = m_objectTemperature; + jobject["AccelerometerX"] = m_accelerometerX; + jobject["AccelerometerY"] = m_accelerometerY; + jobject["AccelerometerZ"] = m_accelerometerZ; + jobject["Altitude"] = m_altitude; + jobject["Light"] = m_light; + jobject["Humidity"] = m_humidity; + QJsonDocument doc( jobject ); + + return doc.toJson(); + \endcode + + JSON has several advantages: + + \list + \li Textual JSON is declarative, which makes it readable to humans + \li The information is structured + \li Exchanging generic information is easy + \li JSON allows extending messages with additional values + \li Many solutions exist to receive and parse JSON in cloud-based solutions + \endlist + + \l CBOR is the Concise Binary Object Representation, a very compact form of + binary data encoding that is a superset of JSON. It was created by the IETF + Constrained RESTful Environments (CoRE) WG, which has been used in many new + RFCs. CBOR shares many of the advantages of JSON, but sacrifices human + readability for compactness. + + \section1 Advantages of QDataStream Classes + + \l QDataStream is a viable option when the whole flow of data is determined + and not about to change. In addition, both the reader and the writer of the + data must be written in Qt. + + Adding support for this to a class requires two additional operators. + For example, for a class named SensorInformation: + + \code + QDataStream &operator<<(QDataStream &, const SensorInformation &); + QDataStream &operator>>(QDataStream &, SensorInformation &); + \endcode + + The implementation for the serialization is shown below: + + \code + QDataStream &operator<<(QDataStream &out, const SensorInformation &item) + { + QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision(); + out.setFloatingPointPrecision(QDataStream::DoublePrecision); + out << item.m_id + << item.m_ambientTemperature + << item.m_objectTemperature + << item.m_accelerometerX + << item.m_accelerometerY + << item.m_accelerometerZ + << item.m_altitude + << item.m_light + << item.m_humidity; + out.setFloatingPointPrecision(prev); + return out; + } + \endcode + + Deserialization works similarly, but using the \c {>>} operator. + For example, \c {out >> item.m_id}, and so on. + + Usually, using QDataStream is faster than using textual JSON. + + \section1 Advantages of Qt XML C++ Classes + + Qt provides the QDomDocument class that represents the XML document and + two classes for reading and writing the XML through a simple streaming API: + QXmlStreamReader and QXmlStreamWriter. + + QDomDocument class represents the entire XML document. It is the root of the + document tree and provides primary access to the document's data. + + A stream reader reports an XML document as a stream of tokens. This differs + from SAX as SAX applications provide handlers to receive XML events from the + parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the + reader when they are needed. This pulling approach makes it possible to build + recursive descent parsers, allowing XML parsing code to be split into + different methods or classes. + + QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed + entities. Hence, data provided to the stream reader adheres to the + W3C's criteria for well-formed XML, or an error will be raised. Functions + such as \c atEnd(), \c error(), and \c hasError() can be used to test for + such errors and obtain a description of them. + + The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces, + when the namespaceUri is specified when writing elements or attributes. + + \section1 Classes that provide serialization + + \annotatedlist qtserialization +*/ diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc index 45934a29d0..8cee601c67 100644 --- a/src/corelib/doc/src/resource-system.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -110,6 +110,15 @@ \snippet resource-system/application.pro 1 + This creates a resource of several \c{.png} files, that are addressable + like this: \c{":/images/copy.png"}. + + If the directory layout of the files you want to embed into the resource + doesn't match the expectations of the application, you can specify + \c{resources.base}. \c base is a path prefix that denotes the root point of + the file's alias. In the example above, if \c{resources.base} is set to + \c{"images"}, then \c{copy.png} is addressable as \c{":/copy.png"}. + \section1 Runtime API Qt API that deals with iterating and reading files has built-in support for |