diff options
Diffstat (limited to 'src/corelib/doc')
75 files changed, 1507 insertions, 305 deletions
diff --git a/src/corelib/doc/include/QtCoreDoc b/src/corelib/doc/include/QtCoreDoc index f3c875e49a..5f5490cbc9 100644 --- a/src/corelib/doc/include/QtCoreDoc +++ b/src/corelib/doc/include/QtCoreDoc @@ -1,3 +1,4 @@ #include <QtCore/QtCore> #include "../../platform/android/qandroidextras_p.h" #include "../../kernel/qpermissions.h" +#include "../../tools/qatomicscopedvaluerollback_p.h" diff --git a/src/corelib/doc/qtcore.qdocconf b/src/corelib/doc/qtcore.qdocconf index a3966397f8..4ed46ae6dd 100644 --- a/src/corelib/doc/qtcore.qdocconf +++ b/src/corelib/doc/qtcore.qdocconf @@ -60,5 +60,11 @@ excludefiles += ../kernel/qtestsupport_core.cpp navigation.landingpage = "Qt Core" navigation.cppclassespage = "Qt Core C++ Classes" -# Fail the documentation build if there are more warnings than the limit -warninglimit = 0 +# Highlighted examples in Data Processing & IO category +manifestmeta.highlighted.names = \ + "QtCore/Mandelbrot" \ + "QtCore/Serialization Converter" \ + "QtCore/QXmlStream Bookmarks Example" + +# Temporarily allow warning: No such parameter 'other' in QFlags::operator=() +warninglimit = 1 diff --git a/src/corelib/doc/snippets/cmake-macros/deployment.cmake b/src/corelib/doc/snippets/cmake-macros/deployment.cmake index 754e3ee759..ef7aa726c0 100644 --- a/src/corelib/doc/snippets/cmake-macros/deployment.cmake +++ b/src/corelib/doc/snippets/cmake-macros/deployment.cmake @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: BSD-3-Clause +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #! [qt_generate_deploy_script_example] cmake_minimum_required(VERSION 3.16...3.22) diff --git a/src/corelib/doc/snippets/cmake-macros/examples.cmake b/src/corelib/doc/snippets/cmake-macros/examples.cmake index 3afaec0fda..09b7470962 100644 --- a/src/corelib/doc/snippets/cmake-macros/examples.cmake +++ b/src/corelib/doc/snippets/cmake-macros/examples.cmake @@ -1,11 +1,37 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: BSD-3-Clause +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -#! [qt_wrap_cpp] +#! [qt_wrap_cpp_1] set(SOURCES myapp.cpp main.cpp) qt_wrap_cpp(SOURCES myapp.h) qt_add_executable(myapp ${SOURCES}) -#! [qt_wrap_cpp] +#! [qt_wrap_cpp_1] + +#! [qt_wrap_cpp_2] +set(SOURCES myapp.cpp main.cpp) +qt_wrap_cpp(SOURCES myapp.h + TARGET myapp + OPTIONS + "$<$<CONFIG:Debug>:-DMY_OPTION_FOR_DEBUG>" + "-DDEFINE_CMDLINE_SIGNAL=void cmdlineSignal(const QMap<int, int> &i)" + "$<$<CONFIG:Debug>:-DDEFINE_CMDLINE_SIGNAL_IN_GENEX=void cmdlineSignal(const QMap<int$<COMMA> int$<ANGLE-R> &i)>") +qt_add_executable(myapp ${SOURCES}) +#! [qt_wrap_cpp_2] + +#! [qt_wrap_cpp_3] +set(SOURCES myapp.cpp main.cpp) +qt_wrap_cpp(SOURCES myapp.h + TARGET myapp) +qt_add_executable(myapp ${SOURCES}) +target_compile_definitions(myapp PRIVATE "$<$<CONFIG:Debug>:MY_OPTION_FOR_DEBUG>" + "DEFINE_CMDLINE_SIGNAL=void cmdlineSignal(const QMap<int, int> &i)" + "$<$<BOOL:TRUE>:DEFINE_CMDLINE_SIGNAL_IN_GENEX=void cmdlineSignal(const QMap<int$<COMMA> int$<ANGLE-R> &i)>") +#! [qt_wrap_cpp_3] + +#! [qt_wrap_cpp_4] +qt_add_executable(myapp myapp.cpp main.cpp) +qt_wrap_cpp("" myapp.cpp TARGET myapp) +#! [qt_wrap_cpp_4] #! [qt_add_resources] set(SOURCES main.cpp) diff --git a/src/corelib/doc/snippets/cmake-macros/examples.cpp b/src/corelib/doc/snippets/cmake-macros/examples.cpp new file mode 100644 index 0000000000..b17fcd8e77 --- /dev/null +++ b/src/corelib/doc/snippets/cmake-macros/examples.cpp @@ -0,0 +1,16 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [qt_wrap_cpp_4] +// myapp.cpp +#include "myapp.h" +#include <QObject> + +class MyApp : public QObject { + Q_OBJECT +public: + MyApp() = default; +}; + +#include "myapp.moc" +//! [qt_wrap_cpp_4] diff --git a/src/corelib/doc/snippets/code/doc_src_containers.cpp b/src/corelib/doc/snippets/code/doc_src_containers.cpp index 5bcee95d32..b568462492 100644 --- a/src/corelib/doc/snippets/code/doc_src_containers.cpp +++ b/src/corelib/doc/snippets/code/doc_src_containers.cpp @@ -1,6 +1,8 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses + //! [0] class Employee { diff --git a/src/corelib/doc/snippets/code/doc_src_properties.cpp b/src/corelib/doc/snippets/code/doc_src_properties.cpp index bb369e6456..190a843710 100644 --- a/src/corelib/doc/snippets/code/doc_src_properties.cpp +++ b/src/corelib/doc/snippets/code/doc_src_properties.cpp @@ -68,6 +68,9 @@ public: void setPriority(Priority priority) { + if (m_priority == priority) + return; + m_priority = priority; emit priorityChanged(priority); } @@ -93,7 +96,7 @@ object->setProperty("priority", "VeryHigh"); //! [7] -Q_CLASSINFO("Version", "3.0.0") +Q_CLASSINFO("DefaultProperty", "content") //! [7] //! [8] diff --git a/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp b/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp index 201517aa2a..f2b94a7416 100644 --- a/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp @@ -1,15 +1,6 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -//! [0] -double pi = 3.14; -double e = 2.71; - -qSwap(pi, e); -// pi == 2.71, e == 3.14 -//! [0] - - //! [1] QList<Employee *> list; list.append(new Employee("Blackpool", "Stephen")); diff --git a/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc b/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc index 41fc57df40..6ce29308f1 100644 --- a/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc +++ b/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc @@ -1,5 +1,5 @@ // Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [0] QObject::connect: Cannot queue arguments of type 'MyType' diff --git a/src/corelib/doc/snippets/code/doc_src_resources.qdoc b/src/corelib/doc/snippets/code/doc_src_resources.qdoc index f5a12ee86a..70c2a7b7ab 100644 --- a/src/corelib/doc/snippets/code/doc_src_resources.qdoc +++ b/src/corelib/doc/snippets/code/doc_src_resources.qdoc @@ -1,5 +1,5 @@ // Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [0] <file alias="cut-img.png">images/cut.png</file> diff --git a/src/corelib/doc/snippets/code/qlogging/qlogging.cpp b/src/corelib/doc/snippets/code/qlogging/qlogging.cpp index d1c3c7b00d..e61eb70df3 100644 --- a/src/corelib/doc/snippets/code/qlogging/qlogging.cpp +++ b/src/corelib/doc/snippets/code/qlogging/qlogging.cpp @@ -1,14 +1,16 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses + #include <QtGui> #include <QtDebug> -#include <QDeclarativeComponent> +#include <QQmlComponent> //! [1] - void statusChanged(QDeclarativeComponent::Status status) { - if (status == QDeclarativeComponent::Error) { - foreach (const QDeclarativeError &error, component->errors()) { + void statusChanged(QQmlComponent::Status status) { + if (status == QQmlComponent::Error) { + for (const QQmlError &error: std::as_const(component->errors())) { const QByteArray file = error.url().toEncoded(); QMessageLogger(file.constData(), error.line(), 0).debug() << error.description(); } 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 70698cd7e0..25d3abf67e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp @@ -210,37 +210,26 @@ const TInputType &myMin(const TInputType &value1, const TInputType &value2) //! [23] -#include <qapplication.h> +#include <QApplication> #include <stdio.h> #include <stdlib.h> -void myMessageOutput(QtMsgType type, const QMessageLogContext &context, const QString &msg) +QtMessageHandler originalHandler = nullptr; + +void logToFile(QtMsgType type, const QMessageLogContext &context, const QString &msg) { - QByteArray localMsg = msg.toLocal8Bit(); - const char *file = context.file ? context.file : ""; - const char *function = context.function ? context.function : ""; - switch (type) { - case QtDebugMsg: - fprintf(stderr, "Debug: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function); - break; - case QtInfoMsg: - fprintf(stderr, "Info: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function); - break; - case QtWarningMsg: - fprintf(stderr, "Warning: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function); - break; - case QtCriticalMsg: - fprintf(stderr, "Critical: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function); - break; - case QtFatalMsg: - fprintf(stderr, "Fatal: %s (%s:%u, %s)\n", localMsg.constData(), file, context.line, function); - break; - } + QString message = qFormatLogMessage(type, context, msg); + static FILE *f = fopen("log.txt", "a"); + fprintf(f, "%s\n", qPrintable(message)); + fflush(f); + + if (originalHandler) + *originalHandler(type, context, msg); } int main(int argc, char **argv) { - qInstallMessageHandler(myMessageOutput); + originalHandler = qInstallMessageHandler(logToFile); QApplication app(argc, argv); ... return app.exec(); diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qabstractfileengine.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qabstractfileengine.cpp index 8c80ec1eba..4300fc2da9 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qabstractfileengine.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qabstractfileengine.cpp @@ -1,17 +1,21 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +using namespace Qt::StringLiterals; + //! [0] class ZipEngineHandler : public QAbstractFileEngineHandler { public: - QAbstractFileEngine *create(const QString &fileName) const override; + std::unique_ptr<QAbstractFileEngine> create(const QString &fileName) const override; }; -QAbstractFileEngine *ZipEngineHandler::create(const QString &fileName) const +std::unique_ptr<QAbstractFileEngine> ZipEngineHandler::create(const QString &fileName) const { // ZipEngineHandler returns a ZipEngine for all .zip files - return fileName.toLower().endsWith(".zip") ? new ZipEngine(fileName) : 0; + if (fileName.toLower().endsWith(".zip"_L1)) + return std::make_unique<ZipEngine>(fileName); + return {}; } int main(int argc, char **argv) @@ -27,21 +31,24 @@ int main(int argc, char **argv) } //! [0] - //! [1] -QAbstractSocketEngine *ZipEngineHandler::create(const QString &fileName) const +std::unique_ptr<QAbstractFileEngine> ZipEngineHandler::create(const QString &fileName) const { // ZipEngineHandler returns a ZipEngine for all .zip files - return fileName.toLower().endsWith(".zip") ? new ZipEngine(fileName) : 0; + if (fileName.toLower().endsWith(".zip"_L1)) + return std::make_unique<ZipEngine>(fileName); + else + return {}; } //! [1] //! [2] -QAbstractFileEngineIterator * -CustomFileEngine::beginEntryList(QDir::Filters filters, const QStringList &filterNames) +QAbstractFileEngine::IteratorUniquePtr +CustomFileEngine::beginEntryList(const QString &path, QDir::Filters filters, + const QStringList &filterNames) { - return new CustomFileEngineIterator(filters, filterNames); + return std::make_unique<CustomFileEngineIterator>(path, filters, filterNames); } //! [2] @@ -50,25 +57,23 @@ CustomFileEngine::beginEntryList(QDir::Filters filters, const QStringList &filte class CustomIterator : public QAbstractFileEngineIterator { public: - CustomIterator(const QStringList &nameFilters, QDir::Filters filters) - : QAbstractFileEngineIterator(nameFilters, filters), index(0) + CustomIterator(const QString &path, const QStringList &nameFilters, QDir::Filters filters) + : QAbstractFileEngineIterator(path, nameFilters, filters), index(0) { // In a real iterator, these entries are fetched from the // file system based on the value of path(). entries << "entry1" << "entry2" << "entry3"; } - bool hasNext() const override - { - return index < entries.size() - 1; - } - - QString next() override + bool advance() override { - if (!hasNext()) - return QString(); - ++index; - return currentFilePath(); + if (entries.isEmpty()) + return false; + if (index < entries.size() - 1) { + ++index; + return true; + } + return false; } QString currentFileName() override diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdirlisting.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdirlisting.cpp new file mode 100644 index 0000000000..231bf48d26 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdirlisting.cpp @@ -0,0 +1,70 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QDirListing> + +using namespace Qt::StringLiterals; + +[[maybe_unused]] static void func() { +{ +//! [0] +using ItFlag = QDirListing::IteratorFlag; +for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) { + qDebug() << dirEntry.filePath(); + // /etc/. + // /etc/.. + // /etc/X11 + // /etc/X11/fs + // ... +} +//! [0] +} + +{ +//! [1] +using ItFlag = QDirListing::IteratorFlag; +QDirListing dirList(u"/sys"_s, QStringList{u"scaling_cur_freq"_s}, + QDir::NoFilter, ItFlag::Recursive); +for (const auto &dirEntry : dirList) { + QFile f(dirEntry.filePath()); + f.open(QIODevice::ReadOnly); + qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz"; +} +//! [1] +} + +{ +//! [2] +QDirListing audioFileIt(u"/home/johndoe/"_s, {"*.mp3", "*.wav"}, QDir::Files); +//! [2] +} + +{ +//! [3] +using ItFlag = QDirListing::IteratorFlag; +for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) { + // Faster + if (dirEntry.fileName().endsWith(u".conf")) { /* ... */ } + + // This works, but might be potentially slower, since it has to construct a + // QFileInfo, whereas (depending on the implemnetation) the fileName could + // be known already + if (dirEntry.fileInfo().fileName().endsWith(u".conf")) { /* ... */ } +} +//! [3] +} + +{ +//! [4] +using ItFlag = QDirListing::IteratorFlag; +for (const auto &dirEntry : QDirListing(u"/etc"_s, ItFlag::Recursive)) { + // Both approaches are the same, because DirEntry will have to construct + // a QFileInfo to get this info (for example, by calling system stat()) + + if (dirEntry.size() >= 4'000 /* 4KB */) { /* ...*/ } + if (dirEntry.fileInfo().size() >= 4'000 /* 4KB */) { /* ... */ } +} +//! [4] +} + +} diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qfileinfo.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qfileinfo.cpp index 9e548afafc..a8dd621111 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qfileinfo.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qfileinfo.cpp @@ -1,11 +1,21 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QDir> +#include <QFileInfo> +using namespace Qt::StringLiterals; + +[[maybe_unused]] static void func() +{ +{ //![newstuff] - QFileInfo fi("c:/temp/foo"); => fi.absoluteFilePath() => "C:/temp/foo" + QFileInfo fi("c:/temp/foo"); + qDebug() << fi.absoluteFilePath(); // "C:/temp/foo" //![newstuff] +} +{ //! [0] #ifdef Q_OS_UNIX @@ -22,7 +32,7 @@ info2.size(); // returns 56201 #endif //! [0] - +} //! [1] #ifdef Q_OS_WIN @@ -41,7 +51,7 @@ info2.size(); // returns 63942 #endif //! [1] - +{ //! [2] QFileInfo info("/usr/bin/env"); @@ -53,50 +63,60 @@ info.setFile("/etc/hosts"); path = info.absolutePath(); // path = /etc base = info.baseName(); // base = hosts //! [2] +} +{ //! [3] QFileInfo fi("/tmp/archive.tar.gz"); QString name = fi.fileName(); // name = "archive.tar.gz" //! [3] +} - +{ //! [4] QFileInfo fi("/Applications/Safari.app"); QString bundle = fi.bundleName(); // name = "Safari" //! [4] +} - +{ //! [5] QFileInfo fi("/tmp/archive.tar.gz"); QString base = fi.baseName(); // base = "archive" //! [5] +} - +{ //! [6] QFileInfo fi("/tmp/archive.tar.gz"); QString base = fi.completeBaseName(); // base = "archive.tar" //! [6] +} - +{ //! [7] QFileInfo fi("/tmp/archive.tar.gz"); QString ext = fi.completeSuffix(); // ext = "tar.gz" //! [7] +} - +{ //! [8] QFileInfo fi("/tmp/archive.tar.gz"); QString ext = fi.suffix(); // ext = "gz" //! [8] +} - +{ +QString fileName = "foo"; //! [9] QFileInfo info(fileName); if (info.isSymLink()) fileName = info.symLinkTarget(); //! [9] +} - +{ //! [10] QFileInfo fi("/tmp/archive.tar.gz"); if (fi.permission(QFile::WriteUser | QFile::ReadGroup)) @@ -104,3 +124,24 @@ if (fi.permission(QFile::WriteUser | QFile::ReadGroup)) if (fi.permission(QFile::WriteGroup | QFile::WriteOther)) qWarning("The group or others can change the file"); //! [10] +} + +{ +//! [11] +// Given a current working directory of "/home/user/Documents/memos/" +QFileInfo info1(u"relativeFile"_s); +qDebug() << info1.absolutePath(); // "/home/user/Documents/memos/" +qDebug() << info1.baseName(); // "relativeFile" +qDebug() << info1.absoluteDir(); // QDir(u"/home/user/Documents/memos"_s) +qDebug() << info1.absoluteDir().path(); // "/home/user/Documents/memos" + +// A QFileInfo on a dir +QFileInfo info2(u"/home/user/Documents/memos"_s); +qDebug() << info2.absolutePath(); // "/home/user/Documents" +qDebug() << info2.baseName(); // "memos" +qDebug() << info2.absoluteDir(); // QDir(u"/home/user/Documents"_s) +qDebug() << info2.absoluteDir().path(); // "/home/user/Documents" +//! [11] +} + +} diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp index d11368a83d..93029274b1 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp @@ -1,6 +1,8 @@ // Copyright (C) 2014 Ivan Komissarov // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses + //! [0] QStorageInfo storage(qApp->applicationDirPath()); if (storage.isValid() && storage.isReady()) { 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 f002ea6fd5..945f3ae3e7 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp @@ -39,7 +39,7 @@ sock.connectToHost(url.host(), url.port(80)); //! [4] -http://www.example.com/cgi-bin/drawgraph.cgi?type(pie)color(green) +http://www.example.com/cgi-bin/drawgraph.cgi?type,pie;color,green //! [4] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qcoreapplication.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qcoreapplication.cpp index 2a3a27e94b..8087ff8f8b 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qcoreapplication.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qcoreapplication.cpp @@ -1,6 +1,8 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses + //! [0] QMouseEvent event(QEvent::MouseButtonPress, pos, 0, 0, 0); QApplication::sendEvent(mainWindow, &event); @@ -13,12 +15,6 @@ connect(quitButton, &QPushButton::clicked, &app, &QCoreApplication::quit, Qt::Qu //! [1] -//! [2] -foreach (const QString &path, app.libraryPaths()) - do_something(path); -//! [2] - - //! [3] // Called once QCoreApplication exists static void preRoutineMyDebugTool() diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp index a3b366a588..f7440f2bb0 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp @@ -63,25 +63,25 @@ //! [7] //! [8] - return d1.deadlineNSecs() == d2.deadlineNSecs(); + return lhs.deadlineNSecs() == rhs.deadlineNSecs(); //! [8] //! [9] - return d1.deadlineNSecs() != d2.deadlineNSecs(); + return lhs.deadlineNSecs() != rhs.deadlineNSecs(); //! [9] //! [10] - return d1.deadlineNSecs() < d2.deadlineNSecs(); + return lhs.deadlineNSecs() < rhs.deadlineNSecs(); //! [10] //! [11] - return d1.deadlineNSecs() <= d2.deadlineNSecs(); + return lhs.deadlineNSecs() <= rhs.deadlineNSecs(); //! [11] //! [12] - return d1.deadlineNSecs() > d2.deadlineNSecs(); + return lhs.deadlineNSecs() > rhs.deadlineNSecs(); //! [12] //! [13] - return d1.deadlineNSecs() >= d2.deadlineNSecs(); + return lhs.deadlineNSecs() >= rhs.deadlineNSecs(); //! [13] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qmimedata.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmimedata.cpp index 36cbdefa1c..c6a48c8827 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmimedata.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmimedata.cpp @@ -1,6 +1,8 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses + //! [0] void MyWidget::dragEnterEvent(QDragEnterEvent *event) { diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp index 1f3789c635..e3bbac7a3c 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp @@ -366,7 +366,7 @@ QPushButton *button = parentWidget->findChild<QPushButton *>("button1", Qt::Find //! [42] -QListWidget *list = parentWidget->findChild<QListWidget *>(QString(), Qt::FindDirectChildrenOnly); +QListWidget *list = parentWidget->findChild<QListWidget *>(Qt::FindDirectChildrenOnly); //! [42] @@ -469,3 +469,16 @@ const bool wasBlocked = someQObject->blockSignals(true); // no signals here someQObject->blockSignals(wasBlocked); //! [54] + +{ +//! [invalid-timer-id] + QObject *obj; + ... + int id = obj->startTimer(100ms); + if (id > Qt::TimerId::Invalid) + // The timer has been started successfully + + if (id > 0) // Equivalent, albeit less readable + // The timer has been started successfully +//! [invalid-timer-id] +} diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qvariant.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qvariant.cpp index dcae4b6934..7f3f1ce7a0 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qvariant.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qvariant.cpp @@ -1,6 +1,8 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses + //! [0] QDataStream out(...); QVariant v(123); // The variant now contains an int diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp index 51b6bbbf46..acb5a6272e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp @@ -183,7 +183,7 @@ using namespace Qt::StringLiterals; //! [21] //! [22] - void appendMap(QCborStreamWriter &writer, const QList<QPair<int, QString>> &values) + void appendMap(QCborStreamWriter &writer, const QList<std::pair<int, QString>> &values) { writer.startMap(); for (const auto pair : values) { @@ -271,12 +271,12 @@ using namespace Qt::StringLiterals; { QString result; auto r = reader.readString(); - while (r.code == QCborStreamReader::Ok) { + while (r.status == QCborStreamReader::Ok) { result += r.data; r = reader.readString(); } - if (r.code == QCborStreamReader::Error) { + if (r.status == QCborStreamReader::Error) { // handle error condition result.clear(); } @@ -289,12 +289,12 @@ using namespace Qt::StringLiterals; { QBytearray result; auto r = reader.readBytearray(); - while (r.code == QCborStreamReader::Ok) { + while (r.status == QCborStreamReader::Ok) { result += r.data; r = reader.readByteArray(); } - if (r.code == QCborStreamReader::Error) { + if (r.status == QCborStreamReader::Error) { // handle error condition result.clear(); } diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp index 296a341b11..dfdebe6a76 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] - QDataStream &operator<<(QDataStream &, const QXxx &); - QDataStream &operator>>(QDataStream &, QXxx &); +QDataStream &operator<<(QDataStream &, const QXxx &); +QDataStream &operator>>(QDataStream &, QXxx &); //! [0] //! [1] - QDataStream & operator<< (QDataStream& stream, const QImage& image); - QDataStream & operator>> (QDataStream& stream, QImage& image); +QDataStream &operator<<(QDataStream &stream, const QImage &image); +QDataStream &operator>>(QDataStream &stream, QImage &image); //! [1] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp index 65e7234608..a4fecc41f9 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp @@ -472,4 +472,10 @@ QByteArray byteArray = "test"; emscripten::val uint8array = QByteArray::toEcmaUint8Array(byteArray); //! [56] +//! [57] +QByteArray x = "Five pineapples"_ba; +x.slice(5); // x == "pineapples" +x.slice(4, 3); // x == "app" +//! [57] + } diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstaticlatin1stringmatcher.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstaticlatin1stringmatcher.cpp new file mode 100644 index 0000000000..ae6e19e471 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstaticlatin1stringmatcher.cpp @@ -0,0 +1,8 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +//! [0] +static constexpr auto matcher = qMakeStaticCaseSensitiveLatin1StringViewMatcher("needle"); +//! [0] +//! [1] +static constexpr auto matcher = qMakeStaticCaseInsensitiveLatin1StringViewMatcher("needle"); +//! [1] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp index e7bd39c95c..b5bfc9cd55 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp @@ -34,3 +34,27 @@ while (new_data_available()) { encoded += fromUtf16(chunk); } //! [3] + +{ +//! [4] +QByteArray encodedString = "..."; +auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); +auto data = toUtf16(encodedString); // data's type is QStringDecoder::EncodedData<const QByteArray &> +QString string = toUtf16(encodedString); // Implicit conversion to QString + +// Here you have to cast "data" to QString +auto func = [&]() { return !toUtf16.hasError() ? QString(data) : u"foo"_s; } +//! [4] +} + +{ +//! [5] +QString string = "..."; +auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); +auto data = fromUtf16(string); // data's type is QStringEncoder::DecodedData<const QString &> +QByteArray encodedString = fromUtf16(string); // Implicit conversion to QByteArray + +// Here you have to cast "data" to QByteArray +auto func = [&]() { return !fromUtf16.hasError() ? QByteArray(data) : "foo"_ba; } +//! [5] +} diff --git a/src/corelib/doc/snippets/code/src_gui_itemviews_qidentityproxymodel.cpp b/src/corelib/doc/snippets/code/src_gui_itemviews_qidentityproxymodel.cpp index 52934b6159..4ef1891cdb 100644 --- a/src/corelib/doc/snippets/code/src_gui_itemviews_qidentityproxymodel.cpp +++ b/src/corelib/doc/snippets/code/src_gui_itemviews_qidentityproxymodel.cpp @@ -17,10 +17,16 @@ class DateFormatProxyModel : public QIdentityProxyModel return QIdentityProxyModel::data(index, role); const QDateTime dateTime = sourceModel()->data(SourceClass::DateRole).toDateTime(); - return dateTime.toString(m_formatString); } + QMap<int, QVariant> itemData(const QModelIndex &proxyIndex) const override + { + QMap<int, QVariant> map = QIdentityProxyModel::itemData(proxyIndex); + map[Qt::DisplayRole] = data(proxyIndex); + return map; + } + private: QString m_formatString; }; diff --git a/src/corelib/doc/snippets/customtype/customtypeexample.cpp b/src/corelib/doc/snippets/customtype/customtypeexample.cpp new file mode 100644 index 0000000000..afa2c4b268 --- /dev/null +++ b/src/corelib/doc/snippets/customtype/customtypeexample.cpp @@ -0,0 +1,90 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QCoreApplication> +#include <QDebug> +#include <QVariant> + +//message.h + +//! [custom type definition] +class Message +{ +public: + Message() = default; + ~Message() = default; + Message(const Message &) = default; + Message &operator=(const Message &) = default; + + Message(const QString &body, const QStringList &headers); + + QStringView body() const; + QStringList headers() const; + +private: + QString m_body; + QStringList m_headers; +}; +//! [custom type definition] + +//! [custom type meta-type declaration] +Q_DECLARE_METATYPE(Message); +//! [custom type meta-type declaration] + +//! [custom type streaming operator declaration] +QDebug operator<<(QDebug dbg, const Message &message); +//! [custom type streaming operator declaration] + +// message.cpp + +//! [custom type streaming operator] +QDebug operator<<(QDebug dbg, const Message &message) +{ + const QList<QStringView> pieces = message.body().split(u"\r\n", Qt::SkipEmptyParts); + if (pieces.isEmpty()) + dbg.nospace() << "Message()"; + else if (pieces.size() == 1) + dbg.nospace() << "Message(" << pieces.first() << ")"; + else + dbg.nospace() << "Message(" << pieces.first() << " ...)"; + return dbg; +} +//! [custom type streaming operator] + +//! [getter functions] +QStringView Message::body() const +{ + return m_body; +} + +QStringList Message::headers() const +{ + return m_headers; +} +//! [getter functions] + +//main.cpp + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QStringList headers; + headers << "Subject: Hello World" + << "From: address@example.com"; + QString body = "This is a test.\r\n"; + //! [printing a custom type] + Message message(body, headers); + qDebug() << "Original:" << message; + //! [printing a custom type] + //! [storing a custom value] + QVariant stored; + stored.setValue(message); + //! [storing a custom value] + qDebug() << "Stored:" << stored; + //! [retrieving a custom value] + Message retrieved = qvariant_cast<Message>(stored); + qDebug() << "Retrieved:" << retrieved; + retrieved = qvariant_cast<Message>(stored); + qDebug() << "Retrieved:" << retrieved; + //! [retrieving a custom value] + return 0; +} diff --git a/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp b/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp index 235d8b27db..e2e97fa11c 100644 --- a/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp +++ b/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp @@ -14,7 +14,7 @@ ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent) QGridLayout *gridLayout = new QGridLayout(this); for (int i = 0; i < texts.size(); ++i) { QPushButton *button = new QPushButton(texts[i]); - connect(button, &QPushButton::clicked, signalMapper, &QSignalMapper::map); + connect(button, &QPushButton::clicked, signalMapper, qOverload<>(&QSignalMapper::map)); //! [0] //! [1] signalMapper->setMapping(button, texts[i]); gridLayout->addWidget(button, i / 3, i % 3); diff --git a/src/corelib/doc/snippets/qstring/main.cpp b/src/corelib/doc/snippets/qstring/main.cpp index c6f35339c6..8b39ae2f13 100644 --- a/src/corelib/doc/snippets/qstring/main.cpp +++ b/src/corelib/doc/snippets/qstring/main.cpp @@ -41,6 +41,7 @@ public: void firstFunction(); void leftJustifiedFunction(); void slicedFunction(); + void sliceFunction(); void numberFunction(); void prependFunction(); @@ -909,6 +910,15 @@ void Widget::arrayOperator() //! [85] } +void Widget::sliceFunction() +{ + //! [86] + QString x = u"Nine pineapples"_s; + x.slice(5); // x == "pineapples" + x.slice(4, 3); // x == "app" + //! [86] +} + int main(int argc, char *argv[]) { diff --git a/src/corelib/doc/snippets/qstring/stringbuilder.cpp b/src/corelib/doc/snippets/qstring/stringbuilder.cpp index a48f9858b3..c3a709bd4c 100644 --- a/src/corelib/doc/snippets/qstring/stringbuilder.cpp +++ b/src/corelib/doc/snippets/qstring/stringbuilder.cpp @@ -27,10 +27,10 @@ using namespace Qt::StringLiterals; //! [6] QString str("QStringBuilder"); - // "s" type is deduced as QStringBuilder + // "s" type is deduced as QStringBuilder<...> auto s = "Like hot glue, " % str % " concatenates strings"; - // Similarly the return type of this lambda is deduced as QStringBuilder + // Similarly the return type of this lambda is deduced as QStringBuilder<...> auto concatenateStr = []() { return "Like hot glue, " % str % " concatenates strings"; }; @@ -39,7 +39,7 @@ using namespace Qt::StringLiterals; //! [7] QString s = "Like hot glue, " % str % " concatenates strings"; - // With a lambda, specify a trailing return type + // With a lambda, specify a trailing return type: auto concatenateStr = []() -> QString { return "Like hot glue, " % str % " concatenates strings"; }; diff --git a/src/corelib/doc/snippets/qstringlist/main.cpp b/src/corelib/doc/snippets/qstringlist/main.cpp index e9567fb107..1b7453cf6a 100644 --- a/src/corelib/doc/snippets/qstringlist/main.cpp +++ b/src/corelib/doc/snippets/qstringlist/main.cpp @@ -93,6 +93,13 @@ Widget::Widget(QWidget *parent) // list == ["Bill Clinton", "Bill Murray"] //! [17] + { +//! [18] + QStringList veryLongList; + QStringMatcher matcher(u"Straße", Qt::CaseInsensitive); + QStringList filtered = veryLongList.filter(matcher); +//! [18] + } } int main(int argc, char *argv[]) diff --git a/src/corelib/doc/snippets/resource-system/CMakeLists.txt b/src/corelib/doc/snippets/resource-system/CMakeLists.txt index 267e9a59ad..f0ec0f6816 100644 --- a/src/corelib/doc/snippets/resource-system/CMakeLists.txt +++ b/src/corelib/doc/snippets/resource-system/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: BSD-3-Clause +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause project(my_app) cmake_minimum_required(VERSION 3.16) diff --git a/src/corelib/doc/snippets/resource-system/application.pro b/src/corelib/doc/snippets/resource-system/application.pro index 4b1f1d7635..42c66eba4c 100644 --- a/src/corelib/doc/snippets/resource-system/application.pro +++ b/src/corelib/doc/snippets/resource-system/application.pro @@ -2,9 +2,9 @@ TEMPLATE = app QT += qml widgets -#! [0] +#! [0] #! [qrc] RESOURCES = application.qrc -#! [0] +#! [0] #! [qrc] #! [1] resources.files = \ diff --git a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h index 2f5a53231c..a590e8fd5e 100644 --- a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h +++ b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h @@ -33,6 +33,8 @@ class Counter : public QObject { Q_OBJECT +// Note. The Q_OBJECT macro starts a private section. +// To declare public members, use the 'public:' access modifier. public: Counter() { m_value = 0; } diff --git a/src/corelib/doc/snippets/timers/analogclock.cpp b/src/corelib/doc/snippets/timers/analogclock.cpp index 0e910f405b..5241e57879 100644 --- a/src/corelib/doc/snippets/timers/analogclock.cpp +++ b/src/corelib/doc/snippets/timers/analogclock.cpp @@ -5,6 +5,7 @@ #include "analogclock.h" +// QTimer //! [0] AnalogClock::AnalogClock(QWidget *parent) //! [0] //! [2] @@ -25,6 +26,21 @@ AnalogClock::AnalogClock(QWidget *parent) } //! [7] +//! [analogclock-qchronotimer] +AnalogClock::AnalogClock(QWidget *parent) + + : QWidget(parent) +{ + auto *timer = new QChronoTimer(1s, this); + connect(timer, &QTimer::timeout, this, QOverload<>::of(&AnalogClock::update)); + timer->start(); + ... + ... + setWindowTitle(tr("Analog Clock")); + resize(200, 200); +} +//! [analogclock-qchronotimer] + void AnalogClock::paintEvent(QPaintEvent *) { static const QPoint hourHand[3] = { diff --git a/src/corelib/doc/snippets/timers/timers.cpp b/src/corelib/doc/snippets/timers/timers.cpp index c89db6890c..1a97ba535e 100644 --- a/src/corelib/doc/snippets/timers/timers.cpp +++ b/src/corelib/doc/snippets/timers/timers.cpp @@ -1,8 +1,12 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QChronoTimer> +#include <QObject> #include <QTimer> +using namespace std::chrono; + class Foo : public QObject { public: @@ -35,7 +39,45 @@ Foo::Foo() } } -int main() +// QChronoTimer +class MyWidget : QObject { + MyWidget() + { +//! [qchronotimer-singleshot] + MyWidget widget; + QChronoTimer::singleShot(200ms, &widget, &MyWidget::updateCaption); +//! [qchronotimer-singleshot] +//! [zero-timer] + // The default interval is 0ns + QChronoTimer *timer = new QChronoTimer(this); + connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing); + timer->start(); +//! [zero-timer] + + { +//! [timer-interval-in-ctor] + QChronoTimer *timer = new QChronoTimer(1s, this); + connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing); + timer->start(); +//! [timer-interval-in-ctor] + } + + { +//! [timer-setinterval] + QChronoTimer *timer = new QChronoTimer(this); + connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing); + timer->setInterval(1s); + timer->start(); +//! [timer-setinterval] + } + } + +public Q_SLOTS: + void processOneThing(); +}; + +int main() +{ } diff --git a/src/corelib/doc/src/animation.qdoc b/src/corelib/doc/src/animation.qdoc index 28f88c907a..3d6c1eefa2 100644 --- a/src/corelib/doc/src/animation.qdoc +++ b/src/corelib/doc/src/animation.qdoc @@ -222,7 +222,7 @@ 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 + An independent QPropertyAnimation 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: diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc index 1deeb19bb8..30d7ddaf60 100644 --- a/src/corelib/doc/src/cbor.qdoc +++ b/src/corelib/doc/src/cbor.qdoc @@ -6,6 +6,7 @@ \title CBOR Support in Qt \ingroup qt-basic-concepts \brief An overview of CBOR support in Qt. + \ingroup explanations-dataprocessingandio \ingroup frameworks-technologies @@ -35,7 +36,7 @@ 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 {Parsing and displaying CBOR data}, {Convert Example}, {JSON Save Game Example} + \sa {Parsing and displaying CBOR data}, {Serialization Converter}, {Saving and Loading a Game} \section1 The CBOR Classes diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc index 249326cfd1..8422a688f0 100644 --- a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -35,7 +35,7 @@ find_package(Qt6 REQUIRED COMPONENTS Core) \preliminarycmakevariable \cmakevariableandroidonly -This is normally set by the Android NDK toolchain file. It is written out as +Usually, this variable is set by the Android NDK toolchain file. It is written out as part of the deployment settings for a target. \sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} @@ -54,8 +54,8 @@ part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -This specifies the location of the Android SDK when building for the Android platform. -It is written out as part of the deployment settings for a target. +Specifies the location of the Android SDK when building for the Android platform. +This variable is written out as part of the deployment settings for a target. \sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. */ @@ -63,6 +63,7 @@ It is written out as part of the deployment settings for a target. /*! \page cmake-variable-qt-android-application-arguments.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-manifest-properties \title QT_ANDROID_APPLICATION_ARGUMENTS \target cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS @@ -73,27 +74,32 @@ It is written out as part of the deployment settings for a target. \preliminarycmakevariable \cmakevariableandroidonly -This contains a list of arguments to be passed to Android applications. It is written -out as part of the deployment settings for a target. +Contains a list of arguments to be passed to Android applications. This variable +is written out as part of the deployment settings for a target. \sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} */ /*! -\page cmake-variable-qt-android-deploy-release.html +\page cmake-variable-qt-android-deployment-type.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties -\title QT_ANDROID_DEPLOY_RELEASE -\target cmake-variable-QT_ANDROID_DEPLOY_RELEASE +\title QT_ANDROID_DEPLOYMENT_TYPE +\target cmake-variable-QT_ANDROID_DEPLOYMENT_TYPE -\summary {Set the package type as a release} +\summary {Forces or disables release package signing regardless of the build type.} -\cmakevariablesince 6.5.1 +\cmakevariablesince 6.7 \preliminarycmakevariable \cmakevariableandroidonly -Setting \c{QT_ANDROID_DEPLOY_RELEASE} to true allows to create release package by passing --release -flag to androiddeployqt tool. +When set to \c Release, the \c --release flag is passed to the \c +androiddeployqt tool, regardless of the application build type. When set to +another value, the \c --release flag is never passed to the tool, which +effectively disables release package signing even in Release or RelWithDebInfo +builds. When not set, the default behavior is to use release package signing in +build types other than Debug. \sa {androiddeployqt} */ @@ -101,17 +107,18 @@ flag to androiddeployqt tool. /*! \page cmake_variable-qt-android-multi-abi-forward-vars \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties \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} +\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 +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 @@ -168,8 +175,8 @@ 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. +Set the variable in this way 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 @@ -182,6 +189,7 @@ finalization occurs automatically when using CMake 3.19 or later. /*! \page cmake-variable-qt-android-build-all-abis.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_BUILD_ALL_ABIS \target cmake-variable-QT_ANDROID_BUILD_ALL_ABIS @@ -192,7 +200,7 @@ finalization occurs automatically when using CMake 3.19 or later. \preliminarycmakevariable \cmakevariableandroidonly -The option automatically detects available ABIs of Qt for Android and uses them to +Automatically detects available ABIs of Qt for Android and uses them to build a package. The automatic detection expects the default directory structure supplied by the Qt installer, with the corresponding naming of the directories. \include cmake-android-supported-abis.qdocinc @@ -207,7 +215,7 @@ The typical directory structure looks as below: \endcode The auto-detected paths can be customized using one of \c{QT_PATH_ANDROID_ABI_<ABI>} variables. -The variable is set to FALSE by default. +The variable is set to \c FALSE by default. \sa{QT_PATH_ANDROID_ABI_<ABI>} */ @@ -215,6 +223,7 @@ The variable is set to FALSE by default. /*! \page cmake-variable-qt-android-abis.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_ABIS \target cmake-variable-QT_ANDROID_ABIS @@ -225,10 +234,10 @@ The variable is set to FALSE by default. \preliminarycmakevariable \cmakevariableandroidonly -This variable specifies a list of ABIs to be used to build the project packages. +Specifies a list of ABIs to be used to build the project packages. \include cmake-android-supported-abis.qdocinc Each ABI should have the corresponding Qt for Android either installed or -user-built. It's possible to specify the path to the Qt for Android ABI using +user-built. To specify the path to the Qt for Android ABI, use the corresponding \c{QT_PATH_ANDROID_ABI_<ABI>} variable. \note \c{QT_ANDROID_BUILD_ALL_ABIS} has the higher priority and ignores the @@ -259,16 +268,17 @@ Each variable can be used to specify the path to Qt for Android for the correspo /*! \page cmake-variable-qt-android-sign-aab.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties \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.} +\summary {Signs 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 +Signs 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 @@ -276,7 +286,7 @@ have to be specified by additional environment variables: QT_ANDROID_KEYSTORE_STORE_PASS QT_ANDROID_KEYSTORE_KEY_PASS \endcode -Mentioned variables are used internally by \l{androiddeployqt}. +The mentioned variables are used internally by \l{androiddeployqt}. \sa{androiddeployqt} */ @@ -284,16 +294,17 @@ Mentioned variables are used internally by \l{androiddeployqt}. /*! \page cmake-variable-qt-android-sign-apk.html \ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_SIGN_APK \target cmake-variable-QT_ANDROID_SIGN_APK -\summary {Sign the package with the specified keystore, alias and store password.} +\summary {Signs the 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 +Signs 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 @@ -301,12 +312,56 @@ have to be specified by additional environment variables: QT_ANDROID_KEYSTORE_STORE_PASS QT_ANDROID_KEYSTORE_KEY_PASS \endcode -Mentioned variables are used internally by \l{androiddeployqt}. +The mentioned variables are used internally by \l{androiddeployqt}. \sa{androiddeployqt} */ /*! +\page cmake-variable-qt-android-generate-java-qml-components.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS +\target cmake-variable-QT_ANDROID_GENERATE_JAVA_QML_COMPONENTS + +\summary {Enables the generation of QtQmlComponent-based classes.} +\cmakevariablesince 6.8 +\preliminarycmakevariable +\cmakevariableandroidonly + +This variable enables Java code generation for QML components of the target application. The +generated code will be included in the resulting package. The Java package name of generated +classes will be the same as the Android app package. If the leaf part of the package name is +not the same as the target executable, an extra static class with the same name as the +capitalized target executable will surround all QML modules enclosing Java classes. Each QML +module class, again in a capitalized form, will contain QtQmlComponent extension classes that +represent QML components of that module. +*/ + +\sa{androiddeployqt} +/*! +\page cmake-variable-qt-use-target-android-build-dir.html +\ingroup cmake-variables-qtcore + +\title QT_USE_TARGET_ANDROID_BUILD_DIR +\target cmake-variable-QT_USE_TARGET_ANDROID_BUILD_DIR + +\summary {Enables the use of per-target Android build directories.} + +\cmakevariablesince 6.7 +\preliminarycmakevariable +\cmakevariableandroidonly + +The variable appends the target-specific suffix to the android-build directory. +The variable only takes an effect when it's set in \c CACHE. The variable is +only supported by Qt Creator starting from version 13. +If a single \c CMakeLists.txt contains more than one Android executable and +this option is not set, you will see a warning. To disable the warning, set +\c QT_SKIP_ANDROID_BUILD_DIR_CHECK to \c TRUE. +*/ + +/*! \page cmake-variable-qt-no-collect-build-tree-apk-deps.html \ingroup cmake-variables-qtcore @@ -323,7 +378,7 @@ 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. +To disable this behavior, set this variable to \c TRUE. \sa {qt6_finalize_project}{qt_finalize_project()} \sa {cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}{QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS} @@ -349,7 +404,7 @@ of the currently processed executable target. That includes the target's source scope and its parents. The collected locations are passed to \l androiddeployqt for deployment consideration when resolving dependencies between libraries. -Set \c QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS to \c TRUE to disable this behavior. +To disable this behavior, set this variable to \c TRUE. \sa {qt6_finalize_project}{qt_finalize_project()} \sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS} @@ -366,9 +421,12 @@ Set \c QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS to \c TRUE to disable this behavio \cmakevariablesince 6.0 -When cross-compiling, this must be set to the install location of Qt for the host +When cross-compiling, this variable 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}, -\l{androiddeployqt}, and so on). +\l{androiddeployqt}, and so on). It's possible to reuse pre-installed tools +when compiling Qt for host systems too, by using \c QT_HOST_PATH that points to +a pre-installed host Qt and setting the \c QT_FORCE_FIND_TOOLS to \c ON. The Qt +versions should match in this case. */ /*! @@ -385,7 +443,7 @@ platform. It is used to locate tools to be run on the host (\l{moc}, \l{rcc}, When finalizing an executable target on iOS, \l{qt6_finalize_target}{qt_finalize_target()} will populate the target's \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM property if it hasn't been set. -Set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to true if you want to prevent this. +To prevent this, set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to \c TRUE. */ /*! @@ -403,7 +461,7 @@ When finalizing an executable target on iOS, \l{qt6_finalize_target}{qt_finalize_target()} will populate the target's \c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and \c MACOSX_BUNDLE_GUI_IDENTIFIER properties if they haven't been set. -Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. +To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE. */ /*! @@ -413,7 +471,7 @@ Set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to true if you want to prevent this. \title QT_ENABLE_VERBOSE_DEPLOYMENT \target cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT -\summary {Enables verbose mode of deployment tools} +\summary {Enables verbose mode of deployment tools.} \cmakevariablesince 6.3 \preliminarycmakevariable @@ -442,7 +500,7 @@ must be set before the first \c{find_package(Qt6)} call to have that effect. This configure-phase variable is set by the Core package. It is intended to be used as the first line of any deployment script to ensure access to the deployment APIs provided by Qt. Such deployment scripts do not run during -CMake's configure phase, they are executed during installation or as +CMake's configure phase. They are executed during installation or as part of a post-build rule. The following example shows one way the variable would be used when installing @@ -467,24 +525,79 @@ an application, along with its runtime dependencies: The \l{qt6_standard_project_setup}{qt_standard_project_setup()} command is typically called in the top level \c{CMakeLists.txt} file of a project. In some -scenarios, such projects may be absorbed as a child project of a larger project +scenarios, such a project may be absorbed as a child project of a larger project hierarchy. A parent project may want to prevent any child project from applying changes to the setup. The parent project can achieve this by setting -\c{QT_NO_STANDARD_PROJECT_SETUP} to true before bringing in the child project -via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()} or other similar +\c{QT_NO_STANDARD_PROJECT_SETUP} to \c TRUE before bringing in the child project +via \l{add_subdirectory()}, \l{FetchContent_MakeAvailable()}, or other similar methods provided by CMake. \sa {qt6_standard_project_setup}{qt_standard_project_setup()} */ /*! +\page cmake-variable-qt-i18n-languages.html +\ingroup cmake-variables-qtcore + +\title QT_I18N_TRANSLATED_LANGUAGES +\target cmake-variable-QT_I18N_TRANSLATED_LANGUAGES + +\summary {List of languages to be used for project internationalization.} + +\cmakevariablesince 6.7 + +Specifies a list of languages that are used for project +internationalization. The single languages must be compatible with the +string-based \l QLocale constructor. + +The languages in \c QT_I18N_TRANSLATED_LANGUAGES are used to: +\list + \li Set up executable targets for consuming \c{.qm} files. + \li Automatically construct \c{.ts} file names in + \l{qt6_add_translations}{qt_add_translations()}. +\endlist + +This variable can be conveniently set with the +\l {qt6_standard_project_setup}{qt_standard_project_setup()} command. + +By default, translatable strings are considered to be written in \c{en}. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +\sa {qt6_add_translations}{qt_add_translations()} +*/ + +/*! +\page cmake-variable-qt-i18n-native-language.html +\ingroup cmake-variables-qtcore + +\title QT_I18N_SOURCE_LANGUAGE +\target cmake-variable-QT_I18N_SOURCE_LANGUAGE + +\summary {Specifies the language of translatable strings.} + +\cmakevariablesince 6.7 + +Specifies the language of translatable strings in the source code. +The language must be compatible with the string-based \l QLocale constructor. + +Together with \c{QT_I18N_TRANSLATED_LANGUAGES}, this variable is used to determine the +names of \c{.ts} files for \l{qt6_add_translations}{qt_add_translations()}. + +This variable can be conveniently set with the +\l {qt6_standard_project_setup}{qt_standard_project_setup()} command. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()} +\sa {qt6_add_translations}{qt_add_translations()} +*/ + +/*! \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} +\summary {Path to iOS launch screen storyboard used by all targets.} \cmakevariablesince 6.4 \preliminarycmakevariable diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc index 61826981a1..ac5094e7cb 100644 --- a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -47,8 +47,9 @@ scripts should assume that the working directory is already set to the base install location and just use the prefix-relative \c{QT_DEPLOY_..._DIR} variables. -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR */ /*! @@ -87,7 +88,46 @@ should not be used for that scenario. \include cmake-deploy-runtime-dependencies.qdocinc -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIB_DIR, +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-libexec-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_LIBEXEC_DIR +\target cmake-variable-QT_DEPLOY_LIBEXEC_DIR + +\summary {Prefix-relative subdirectory for deploying program executables on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.7 + +On Unix derivatives, projects should use \c QT_DEPLOY_LIBEXEC_DIR in their +deploy scripts to avoid hard-coding a particular directory in which to deploy +helper executables that are local to the project. + +For example, projects using QtWebEngine would deploy the \c QtWebEngineProcess +executable to this directory. + +\c QT_DEPLOY_LIBEXEC_DIR defaults to the value of \c${CMAKE_INSTALL_LIBEXECDIR} +(usually \c{libexec}), which is provided by CMake's \l{GNUInstallDirs} module. +To change the value of \c QT_DEPLOY_LIBEXEC_DIR, ensure that the project sets +\c{CMAKE_INSTALL_LIBEXECDIR} before the \c Core package is found. + +The \c QT_DEPLOY_LIBEXEC_DIR path is relative to \l{QT_DEPLOY_PREFIX}. + +This variable is not meaningful when deploying into a macOS app bundle and +should not be used for that scenario. + +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR */ @@ -163,8 +203,9 @@ bundle contents. \include cmake-deploy-modified-variable-values.qdocinc -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, + QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR */ /*! @@ -200,8 +241,9 @@ to be deployed to different locations within the app bundle. \include cmake-deploy-modified-variable-values.qdocinc -\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_TRANSLATIONS_DIR +\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, + QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, + QT_DEPLOY_TRANSLATIONS_DIR */ /*! @@ -233,7 +275,7 @@ This variable is not meaningful when deploying on macOS or Windows. \include cmake-deploy-modified-variable-values.qdocinc \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR, - QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR + QT_DEPLOY_LIBEXEC_DIR, QT_DEPLOY_PLUGINS_DIR, 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 a7ad6c75da..4b602d5d07 100644 --- a/src/corelib/doc/src/cmake/cmake-properties.qdoc +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -16,6 +16,7 @@ target properties: \page cmake-target-property-qt-android-deployment-dependencies.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_DEPLOYMENT_DEPENDENCIES \target cmake-target-property-QT_ANDROID_DEPLOYMENT_DEPENDENCIES @@ -47,6 +48,7 @@ is listed before its dependencies, it will fail to load on some devices. \page cmake-target-property-qt-android-extra-libs.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_EXTRA_LIBS \target cmake-target-property-QT_ANDROID_EXTRA_LIBS @@ -85,6 +87,33 @@ library to the MyApp dependencies: add_dependencies(MyApp MyService) \endcode +When adding per-architecture libraries to a multi-abi project, +list all their paths explicitly, rather than rely on variables like +\c CMAKE_ANDROID_ARCH_ABI to dynamically compute the paths. + +Prefer: + +\badcode +set(libs + ${CMAKE_CURRENT_BINARY_DIR}/libA_x86so + ${CMAKE_CURRENT_BINARY_DIR}/libA_x86_64.so + ${CMAKE_CURRENT_BINARY_DIR}/libA_arm64-v8a.so + ${CMAKE_CURRENT_BINARY_DIR}/libA_armeabi-v7a.so +) +set_target_properties(MyApp PROPERTIES QT_ANDROID_EXTRA_LIBS ${libs}) + +# When targeting precompiled libs +target_link_libraries(${CMAKE_PROJECT_NAME} PUBLIC libA_${ANDROID_ABI}) +\endcode + +over: + +\badcode +set_target_properties(MyApp PROPERTIES + QT_ANDROID_EXTRA_LIBS + ${CMAKE_CURRENT_BINARY_DIR}/libA_${CMAKE_ANDROID_ARCH_ABI}.so) +\endcode + \sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} */ @@ -92,6 +121,7 @@ add_dependencies(MyApp MyService) \page cmake-target-property-qt-android-extra-plugins.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_EXTRA_PLUGINS \target cmake-target-property-QT_ANDROID_EXTRA_PLUGINS @@ -123,6 +153,7 @@ mangling is applied to the plugin library. \page cmake-target-property-qt-android-min-sdk-version.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_MIN_SDK_VERSION \target cmake-target-property-QT_ANDROID_MIN_SDK_VERSION @@ -142,6 +173,7 @@ Specifies the minimum Android API level for the target. \page cmake-target-property-qt-android-package-source-dir.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_PACKAGE_SOURCE_DIR \target cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR @@ -175,6 +207,7 @@ then place this directly into the directory specified by this variable. \page cmake-target-property-qt-android-target-sdk-version.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_TARGET_SDK_VERSION \target cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION @@ -194,6 +227,7 @@ Specifies the target Android API level for the target. \page cmake-target-property-qt-android-sdk-build-tools-revision.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_SDK_BUILD_TOOLS_REVISION \target cmake-target-property-QT_ANDROID_SDK_BUILD_TOOLS_REVISION @@ -211,12 +245,63 @@ CMake will attempt to use the latest installed version. */ /*! +\page cmake-target-property-qt-android-package-name.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_PACKAGE_NAME +\target cmake-target-property-QT_ANDROID_PACKAGE_NAME + +\summary {The app's package name.} + +\cmakepropertysince 6.8 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the app's package name. This is usually a unique dot separated +name for the app, that will be used to identify the app on devices or in +the Play Store. For example, "org.qtproject.example.gallery". + +The package name set by this property is passed to the \c build.gradle file +as a \c namespace property, instead of \c AndroidManifest.xml, since the +latter is deprecated since Android Gradle Plugin 7.4. + +The package name considers some words or characters as illegal and the build +will clean such names if any is encountered. An underscore (\c _) either replaces +illegal characters or is appended to illegal words. + +\list + \li Allowed characters: alphanumeric, an underscore or a dot [a-zA-Z0-9_.]. + \li Illegal words: abstract, continue, for, new, switch, assert, default, + if, package, synchronized, boolean, do, goto, private, this, break, + double, implements, protected, throw, byte, else, import, public, + throws, case, enum, instanceof, return, transient, catch, extends, + int, short, try, char, final, interface, static, void, class, finally, + long, strictfp, volatile, const, float, native, super, while. +\endlist + +The default package name for Qt for Android apps is \c org.qtproject.example.<target_name>. + +\note Setting the package name manually in \c build.gradle (via +\c namespace property) takes precedence over \c AndroidManifest.xml +(via \c package attribute), and the latter also takes precedence over +this property. + +For more information, see Android's +\l{Android: Configure the app module}{configure the app module}. + +\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 \title QT_ANDROID_VERSION_CODE \target cmake-target-property-QT_ANDROID_VERSION_CODE +\ingroup cmake-android-manifest-properties \summary {Internal Android app version.} @@ -239,6 +324,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. \title QT_ANDROID_VERSION_NAME \target cmake-target-property-QT_ANDROID_VERSION_NAME +\ingroup cmake-android-manifest-properties \summary {Human-readable Android app version.} @@ -258,6 +344,7 @@ For more information, see \l{Android: App Versioning}{Android App Versioning}. \page cmake-target-property-qt-android-abis.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_ABIS \target cmake-target-property-QT_ANDROID_ABIS @@ -324,6 +411,7 @@ For application-specific QML imports, use \page cmake-target-property-qt-android-deployment-settings-file.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_DEPLOYMENT_SETTINGS_FILE \target cmake-target-property-QT_ANDROID_DEPLOYMENT_SETTINGS_FILE @@ -344,6 +432,7 @@ and overwritten by that command. \page cmake-target-property-qt-android-system-libs-prefix.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_SYSTEM_LIBS_PREFIX \target cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX @@ -361,6 +450,7 @@ when those libraries are installed outside app's native (JNI) library directory. \page cmake-target-property-qt-android-no-deploy-qt-libs.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore +\ingroup cmake-android-build-properties \title QT_ANDROID_NO_DEPLOY_QT_LIBS \target cmake-target-property-QT_ANDROID_NO_DEPLOY_QT_LIBS @@ -453,7 +543,7 @@ the property value overrides the runtime path where the resource file is found. \summary {Specifies that the given files should be empty in the resource file system} -\cmakepropertysince 6.5 +\cmakepropertysince 6.6 \preliminarycmakeproperty When using the target-based variant of \l{qt6_add_resources}{qt_add_resources} @@ -555,6 +645,29 @@ For more information, see \l{https://github.com/emscripten-core/emscripten/blob/ */ /*! +\page cmake-target-property-qt-wasm-maximum-memory.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_WASM_MAXIMUM_MEMORY +\target cmake-target-property-QT_WASM_MAXIMUM_MEMORY + +\summary {Internal WebAssembly maximum memory.} + +\cmakepropertysince 6.7 +\preliminarycmakeproperty +\cmakepropertywebassemblyonly + +Specifies the maximum amount of memory the application can use. Translates into +the Emscripten compiler setting of \c MAXIMUM_MEMORY. The default value +is 4GB, which is the maximum for 32-bit WebAssembly. + +For more information, see the \l{https://github.com/emscripten-core/emscripten/blob/3319a313d3b589624d342b650884caaf8cd9ef30/src/settings.js#L187}{Emscripten compiler settings}. +*/ + + + +/*! \page cmake-target-property-qt-ios-launch-screen.html \ingroup cmake-properties-qtcore \ingroup cmake-target-properties-qtcore diff --git a/src/corelib/doc/src/cmake/cmake-standard-properties.qdoc b/src/corelib/doc/src/cmake/cmake-standard-properties.qdoc new file mode 100644 index 0000000000..a8ece6ba8f --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-standard-properties.qdoc @@ -0,0 +1,24 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page cmake-standard-property-autogen-better-graph-multi-config.html +\ingroup cmake-standard-properties + +\title AUTOGEN_BETTER_GRAPH_MULTI_CONFIG + +\brief Improves the dependency graph for multi-configuration generators when you +set it on a target. + +When this boolean property is enabled, \c{CMake} will generate more per-config targets. +Thus, the dependency graph will be more accurate for multi-configuration +generators and some recompilations will be avoided. + +Since Qt 6.8, this property is enabled by default. For older versions, +you need to enable it manually to use it. +However, \l{qt_extract_metatypes} and \l{qt_add_qml_module} were updated to +support \c{AUTOGEN_BETTER_GRAPH_MULTI_CONFIG} in Qt 6.8, so you will get build +errors, unless you patch the older Qt version to support it. + +See \l{https://cmake.org/cmake/help/latest/prop_tgt/AUTOGEN_BETTER_GRAPH_MULTI_CONFIG.html}{AUTOGEN_BETTER_GRAPH_MULTI_CONFIG} for more information. +*/ diff --git a/src/corelib/doc/src/cmake/policy/qtp0002.qdoc b/src/corelib/doc/src/cmake/policy/qtp0002.qdoc index 4416ac132a..a40344a167 100644 --- a/src/corelib/doc/src/cmake/policy/qtp0002.qdoc +++ b/src/corelib/doc/src/cmake/policy/qtp0002.qdoc @@ -56,8 +56,7 @@ set_target_properties( ) \endcode -\note The \c{OLD} behavior of a policy is deprecated, and may -be removed in the future. +\qtpolicydeprecatedbehavior \sa qt_policy, {Qt CMake policies} diff --git a/src/corelib/doc/src/cmake/policy/qtp0003.qdoc b/src/corelib/doc/src/cmake/policy/qtp0003.qdoc new file mode 100644 index 0000000000..bf11b6f8b5 --- /dev/null +++ b/src/corelib/doc/src/cmake/policy/qtp0003.qdoc @@ -0,0 +1,46 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0003.html +\ingroup qt-cmake-policies +\since 6.7 +\title QTP0003 +\keyword qt_cmake_policy_qtp0003 + +\summary {Consider the BUILD_SHARED_LIBS value when creating Qt libraries.} + +This policy was introduced in Qt 6.7. The policy affects the default type of the +libraries created using \l {CMake Commands in Qt6 Core}{Qt CMake API}, like +\l {qt_add_library}, \l{qt_add_plugin}, \l{qt_add_qml_module}. + +If the policy is set to \c OLD, the default library type that is selected is +aligned with the Qt build type, either \c shared or \c static. + +If the policy is set to \c NEW, the library type is selected according to the +\l {CMake BUILD_SHARED_LIBS Documentation}{BUILD_SHARED_LIBS} value if it's set. +If \c BUILD_SHARED_LIBS is not set, the default library type falls back to the +Qt build type. + +For example, the following code will use the Qt build type as the default +library type for the \c MyLib target, despite the fact \c BUILD_SHARED_LIBS is +set to \c ON: +\badcode +set(BUILD_SHARED_LIBS ON) +... +qt6_add_library(MyLib sourcefile.h sourcefile.cpp) +\endcode + +If you set the QTP0003 to \c NEW before the \l {qt6_add_library}{qt_add_library} +call, \c BUILD_SHARED_LIBS will affect the library default type and \c MyLib +will be the shared library. +\badcode +set(BUILD_SHARED_LIBS ON) +... +qt_policy(SET QTP0003 NEW) +qt6_add_library(MyLib sourcefile.h sourcefile.cpp) +\endcode + +\sa qt_policy, {Qt CMake policies}, 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 66336da4b9..851a2d6210 100644 --- a/src/corelib/doc/src/cmake/qt_add_library.qdoc +++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc @@ -45,8 +45,10 @@ library type created depends on how Qt was built. If Qt was built statically, a static library will be created. Otherwise, a shared library will be created. Note that this is different to how CMake's \c{add_library()} command works, where the \c BUILD_SHARED_LIBS variable controls the type of -library created. The \c{qt_add_library()} command does not consider -\c BUILD_SHARED_LIBS when deciding the library type. +library created. +Since 6.7, the \c{qt_add_library()} command considers \c BUILD_SHARED_LIBS +when deciding the library type only if the variable is set explicitly and +\l {QTP0003} is set to \c NEW. Any \c{sources} provided will be passed through to the internal call to \c{add_library()}. @@ -73,6 +75,6 @@ time. In general, \c MANUAL_FINALIZATION should not be needed unless the project has to support CMake 3.18 or earlier. \sa {qt6_finalize_target}{qt_finalize_target()}, - {qt6_add_executable}{qt_add_executable()} + {qt6_add_executable}{qt_add_executable()}, QTP0003 */ 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 5a7bbdc33f..daa3680070 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 @@ -63,6 +63,7 @@ how to accomplish this. \li \l{cmake-target-property-QT_ANDROID_MIN_SDK_VERSION}{QT_ANDROID_MIN_SDK_VERSION} \li \l{cmake-target-property-QT_ANDROID_PACKAGE_SOURCE_DIR}{QT_ANDROID_PACKAGE_SOURCE_DIR} \li \l{cmake-target-property-QT_ANDROID_TARGET_SDK_VERSION}{QT_ANDROID_TARGET_SDK_VERSION} +\li \l{cmake-target-property-QT_ANDROID_PACKAGE_NAME}{QT_ANDROID_PACKAGE_NAME} \li \l{cmake-target-property-QT_ANDROID_VERSION_NAME}{QT_ANDROID_VERSION_NAME} \li \l{cmake-target-property-QT_ANDROID_VERSION_CODE}{QT_ANDROID_VERSION_CODE} \li \l{cmake-target-property-QT_QML_IMPORT_PATH}{QT_QML_IMPORT_PATH} 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 2eac3f3199..f64960492a 100644 --- a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc +++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc @@ -31,6 +31,7 @@ qt_deploy_runtime_dependencies( [ADDITIONAL_MODULES files...] [GENERATE_QT_CONF] [BIN_DIR bin_dir] + [LIBEXEC_DIR libexec_dir] [LIB_DIR lib_dir] [PLUGINS_DIR plugins_dir] [QML_DIR qml_dir] @@ -39,6 +40,7 @@ qt_deploy_runtime_dependencies( [NO_APP_STORE_COMPLIANCE] [NO_TRANSLATIONS] [NO_COMPILER_RUNTIME] + [DEPLOY_TOOL_OPTIONS] [PRE_INCLUDE_REGEXES regexes...] [PRE_EXCLUDE_REGEXES regexes...] [POST_INCLUDE_REGEXES regexes...] @@ -102,13 +104,41 @@ directory structure. If the \c{GENERATE_QT_CONF} option is given, an appropriate \c{qt.conf} file will be written to the same directory as the \c{executable}. The paths in that \c{qt.conf} file will be based on the \c{CMAKE_INSTALL_xxxDIR} variables, whose defaults are provided by CMake's \l{GNUInstallDirs} module. -You can override some of those defaults with the \c{BIN_DIR}, \c{LIB_DIR}, -\c{PLUGINS_DIR}, and \c{QML_DIR} options, all of which are expected to be -relative to the base install location. A \c{qt.conf} file is always written if -\c{executable} is a macOS app bundle, regardless of whether or not -\c{GENERATE_QT_CONF} is provided. The \c{..._DIR} options are also ignored in -that case, since the directory layout of an app bundle is dictated by Apple's -requirements. + +You can override some of those defaults with the parameters in the following +table, all of which are expected to be relative to the base install location. + +\table +\header + \li parameter + \li affected variable + \li notes +\row + \li \c BIN_DIR + \li \l QT_DEPLOY_BIN_DIR + \li +\row + \li \c LIBEXEC_DIR + \li \l QT_DEPLOY_LIBEXEC_DIR + \li since Qt 6.7 +\row + \li \c LIB_DIR + \li \l QT_DEPLOY_LIB_DIR + \li +\row + \li \c PLUGINS_DIR + \li \l QT_DEPLOY_PLUGINS_DIR + \li +\row + \li \c QML_DIR + \li \l QT_DEPLOY_QML_DIR + \li +\endtable + +A \c{qt.conf} file is always written if \c{executable} is a macOS app bundle, +regardless of whether or not \c{GENERATE_QT_CONF} is provided. The \c{..._DIR} +options are also ignored in that case, since the directory layout of an app +bundle is dictated by Apple's requirements. More verbose output about the deployment steps can be enabled by providing the \c{VERBOSE} option. Alternatively, the \l{QT_ENABLE_VERBOSE_DEPLOYMENT} @@ -132,6 +162,10 @@ in a customized way. For Windows desktop applications, the required runtime files for the compiler are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}. +Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to +the underlying deployment tool. This only has an effect if the underlying +deployment tool is either macdeployqt or windeployqt. + On Linux, deploying runtime dependencies is based on CMake's \c{file(GET_RUNTIME_DEPENDENCIES)} command. The options \c{PRE_INCLUDE_REGEXES}, \c{PRE_EXCLUDE_REGEXES}, \c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, @@ -152,5 +186,13 @@ The default value of \c{POST_EXCLUDE_REGEXES} is constructed from the value of \section1 Example +The following example shows how to deploy an application \c{MyApp}. + \include cmake-deploy-runtime-dependencies.qdocinc + +The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to +pass different options to macdeployqt and windeployqt. + +\include cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc + */ diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc index 7d9cd936ff..7ec8d90f9b 100644 --- a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -52,4 +52,18 @@ example, to pass it to another command or to install it), use the \c OUTPUT_FILES option to provide the name of a variable in which to store its absolute path. +\section1 Automatic metatype extraction + +Since Qt 6.8, if you have not disabled \c{AUTOMOC} and either are using CMake +3.19 or later or are calling \l{qt6_finalize_target}{qt_finalize_target()} +manually, then \c{qt_extract_metatypes()} is automatically called as part of the +finalization step for \l{qt_add_library}. This has no effect if you have +manually called \c{qt_extract_metatypes()} before the finalization, possibly +with custom arguments. However, it does make sure that the metatypes are also +produced if you haven't. This is important if any of the types in the library +are used as part of any QML types any time in the future and has no downsides. + +Furthermore, \l{qt_add_qml_module} automatically invokes +\c{qt_extract_metatypes()} for its 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 f52a0f1661..31d9e4384b 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 @@ -24,6 +24,7 @@ qt_generate_deploy_app_script( [NO_TRANSLATIONS] [NO_COMPILER_RUNTIME] [NO_UNSUPPORTED_PLATFORM_ERROR] + [DEPLOY_TOOL_OPTIONS ...] [PRE_INCLUDE_REGEXES regexes...] [PRE_EXCLUDE_REGEXES regexes...] [POST_INCLUDE_REGEXES regexes...] @@ -74,6 +75,10 @@ customized way. For Windows desktop applications, the required runtime files for the compiler are also installed by default. To prevent this, specify \c{NO_COMPILER_RUNTIME}. +Since Qt 6.7, you can use \c{DEPLOY_TOOL_OPTIONS} to pass additional options to +the underlying deployment tool. This only has an effect if the underlying +deployment tool is either macdeployqt or windeployqt. + For deploying a QML application, use \l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} instead. @@ -93,5 +98,13 @@ unmodified to \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies \section1 Example +The following example shows how to deploy an application \c{MyApp}. + \include cmake-generate-deploy-app-script.qdocinc + +The following example shows how to use the \c{DEPLOY_TOOL_OPTIONS} parameter to +pass different options to macdeployqt and windeployqt. + +\include cmake-generate-deploy-app-script-deploy-tool-options.qdocinc + */ diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc index 4b612206ee..1f81a21cd2 100644 --- a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -8,7 +8,7 @@ \title qt_import_plugins \keyword qt6_import_plugins -\summary {Specifies a custom set of plugins to import for a static Qt build.} +\summary {Specifies a custom set of plugins to import or exclude.} \include cmake-find-package-core.qdocinc @@ -48,17 +48,35 @@ can be used more than once. Qt provides plugin types such as \c imageformats, \c platforms, and \c sqldrivers. +\section2 Dynamic plugins + +If plugins are dynamic libraries, the function controls the plugin deployment. +Using this function, you may exclude specific plugin types from +being packaged into an Android APK, for example: + +\badcode +qt_add_executable(MyApp ...) +... +qt_import_plugins(MyApp EXCLUDE_BY_TYPE imageformats) +\endcode + +In the snippet above, all plugins that have the \c imageformats type will +be excluded when deploying \c MyApp. The resulting Android APK will not +contain any of the \c imageformats plugins. + +If the command isn't used, the target automatically deploys all plugins that +belong to the Qt modules that the target is linked against. + +\section2 Static plugins + If the command isn't used the target automatically links against -a sane set of default plugins, for each Qt module that the target is linked -against. For more information, see +a sane set of default static plugins, for each Qt module that the target is +linked against. For more information, see \l{CMake target_link_libraries Documentation}{target_link_libraries}. Each plugin comes with a C++ stub file that automatically -initializes the plugin. Consequently, any target that links against a plugin -has this C++ file added to its \c SOURCES. - -\note This command imports plugins from static Qt builds only. -On shared builds, it does nothing. +initializes the static plugin. Consequently, any target that links against +a plugin has this C++ file added to its \c SOURCES. \section1 Examples diff --git a/src/corelib/doc/src/cmake/qt_policy.qdoc b/src/corelib/doc/src/cmake/qt_policy.qdoc index 7c44b4d824..6deb7a729c 100644 --- a/src/corelib/doc/src/cmake/qt_policy.qdoc +++ b/src/corelib/doc/src/cmake/qt_policy.qdoc @@ -58,8 +58,7 @@ You can set \c behavior to one of the following options: \li \c{OLD} to explicitly opt-out of it \endlist -\note The \c{OLD} behavior of a policy is deprecated, and may -be removed in the future. +\qtpolicydeprecatedbehavior \sa qt_standard_project_setup 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 458b25bdc9..59b33f599c 100644 --- a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc +++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc @@ -20,6 +20,8 @@ qt_standard_project_setup( [REQUIRES <version>] [SUPPORTS_UP_TO <version>] + [I18N_TRANSLATED_LANGUAGES <language...>] + [I18N_SOURCE_LANGUAGE <language>] ) \endcode @@ -81,7 +83,19 @@ setting the \l{QT_NO_STANDARD_PROJECT_SETUP} variable to true. \sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} \sa qt_policy +\section1 Internationalization + +Since Qt 6.7, it is possible to specify the languages that are used for project +internationalization with the \c I18N_TRANSLATED_LANGUAGES argument. See \l +QT_I18N_TRANSLATED_LANGUAGES for details. + +Use I18N_SOURCE_LANGUAGE to specify the language that translatable strings are +written in. By default, \c en is used. See \l QT_I18N_SOURCE_LANGUAGE for +details. + \section1 Example \include cmake-generate-deploy-app-script.qdocinc + +\sa {Automatic Determination of .ts File Paths}{qt_add_translations()} */ diff --git a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc index 03b7a866a7..3b298a9d7e 100644 --- a/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc +++ b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc @@ -40,9 +40,23 @@ You can set an explicit \c{TARGET}. This will make sure that the target properties \c{INCLUDE_DIRECTORIES} and \c{COMPILE_DEFINITIONS} are also used when scanning the source files with \c{moc}. +Since Qt 6.8, when a source file is passed to \c{qt_wrap_cpp} instead of a +header file to generate a \c{.moc} file for a target, the \c{TARGET} parameter +is needed to set the correct include path for the generated \c{.moc} file in +the source file. As generated \c{.moc} files are added to the target's +sources by \c{qt_wrap_cpp}, they are not added to \c{<VAR>}. + You can set additional \c{OPTIONS} that should be added to the \c{moc} calls. You can find possible options in the \l{moc}{moc documentation}. +The \c{OPTIONS} can evaluate generator expressions when \c{TARGET} is set. +\note If the \c{OPTIONS} include both generator expressions and special +characters, use variables to implement them. For example, use \c{$<ANGLE-R>}, +\c{$<COMMA>} and \c{$<SEMICOLON>} instead of \c{>}, \c{,} and \c{:}. Otherwise, +the generator expression will not be evaluated correctly. \c {OPTIONS} are +wrapped in generator expressions, so you must escape special characters in +them. + \c{DEPENDS} allows you to add additional dependencies for recreation of the generated files. This is useful when the sources have implicit dependencies, like code for a Qt plugin that includes a \c{.json} file using the @@ -50,5 +64,27 @@ Q_PLUGIN_METADATA() macro. \section1 Examples -\snippet cmake-macros/examples.cmake qt_wrap_cpp +\snippet cmake-macros/examples.cmake qt_wrap_cpp_1 + +In the following example, the generator expressions passed to \c{OPTIONS} +will be evaluated since \c{TARGET} is set. The argument is specified this way to +avoid syntax errors in the generator expressions. + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_2 + +The following example uses \l{https://cmake.org/cmake/help/latest/command/target_compile_definitions.html}{target_compile_definitions} +to set \l{https://cmake.org/cmake/help/latest/prop_tgt/COMPILE_DEFINITIONS.html}{COMPILE_DEFINITIONS} which will be added to +\c{OPTIONS}. + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_4 + +\snippet cmake-macros/examples.cpp qt_wrap_cpp_4 + +In the above file, \c{myapp.moc} is included in \c{myapp.cpp}. +To generate the \c{myapp.moc} file, the \c{qt_wrap_cpp} macro is used with the +\c{TARGET} parameter. The first parameter is empty because the \c{.moc} file +and its path will be added to the target's sources and include directories by +the \c{qt_wrap_cpp} macro. + +\snippet cmake-macros/examples.cmake qt_wrap_cpp_4 */ diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index df82830792..847be1bff6 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -351,7 +351,8 @@ the problem exists for all the implicitly shared Qt containers. \section3 Java-Style Iterators - \l{java-style-iterators}{Java-Style iterators} were introduced in Qt 4. Their API is modelled + \l{java-style-iterators}{Java-Style iterators} + are modelled on Java's iterator classes. New code should prefer \l{STL-Style Iterators}. @@ -387,16 +388,16 @@ \l{QHash}. \row \li \l{QMap}<Key, T> - \li Similar to std::map<T>. + \li Similar to std::map<Key, T>. \row \li \l{QMultiMap}<Key, T> - \li Similar to std::multimap<T>. + \li Similar to std::multimap<Key, T>. \row \li \l{QHash}<Key, T> - \li Most similar to std::unordered_map<T>. + \li Most similar to std::unordered_map<Key, T>. \row \li \l{QMultiHash}<Key, T> - \li Most similar to std::unordered_multimap<T>. + \li Most similar to std::unordered_multimap<Key, T>. \endtable diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc index 352a43549d..7922fd9477 100644 --- a/src/corelib/doc/src/custom-types.qdoc +++ b/src/corelib/doc/src/custom-types.qdoc @@ -6,7 +6,7 @@ \title Creating Custom Qt Types \brief How to create and register new types with Qt. - \ingroup best-practices + \ingroup how-to \tableofcontents @@ -37,7 +37,7 @@ The following \c Message class definition includes these members: - \snippet tools/customtype/message.h custom type definition + \snippet customtype/customtypeexample.cpp custom type definition The class also provides a constructor for normal use and two public member functions that are used to obtain the private data. @@ -53,11 +53,14 @@ to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header file where it is defined: - \snippet tools/customtype/message.h custom type meta-type declaration + \snippet customtype/customtypeexample.cpp custom type meta-type declaration This now makes it possible for \c Message values to be stored in QVariant objects - and retrieved later. See the \l{Custom Type Example} for code that demonstrates - this. + and retrieved later: + + \snippet customtype/customtypeexample.cpp storing a custom value + \dots + \snippet customtype/customtypeexample.cpp retrieving a custom value The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as arguments to signals, but \e{only in direct signal-slot connections}. @@ -77,7 +80,7 @@ available for queued signal-slot communication as long as you call it before you make the first connection that uses the type. - The \l{Queued Custom Type Example} declares a \c Block class which is registered + The \l{Queued Custom Type} example declares a \c Block class which is registered in the \c{main.cpp} file: \snippet threads/queuedcustomtype/main.cpp main start @@ -107,18 +110,17 @@ It is often quite useful to make a custom type printable for debugging purposes, as in the following code: - \snippet tools/customtype/main.cpp printing a custom type + \snippet customtype/customtypeexample.cpp printing a custom type This is achieved by creating a streaming operator for the type, which is often defined in the header file for that type: - \snippet tools/customtype/message.h custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator declaration - The implementation for the \c Message type in the \l{Custom Type Example} - goes to some effort to make the printable representation as readable as - possible: + The implementation for the \c Message type here goes to some effort to make the + printable representation as readable as possible: - \snippet tools/customtype/message.cpp custom type streaming operator + \snippet customtype/customtypeexample.cpp custom type streaming operator The output sent to the debug stream can, of course, be made as simple or as complicated as you like. Note that the value returned by this function is @@ -131,9 +133,8 @@ The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation contain more detailed information about their uses and limitations. - The \l{Custom Type Example}{Custom Type} and \l{Queued Custom Type Example} - {Queued Custom Type} examples show how to implement a custom type with the - features outlined in this document. + The \l{Queued Custom Type} example shows how to implement a custom type with + the features outlined in this document. The \l{Debugging Techniques} document provides an overview of the debugging mechanisms discussed above. diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index b1b2e6ba34..65b7eb5a20 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -31,7 +31,11 @@ \li QBitArray \li QBrush \li QByteArray + \li QCborArray + \li QCborMap + \li QCborValue \li QColor + \li QColorSpace \li QCursor \li QDate \li QDateTime @@ -39,32 +43,71 @@ \li QFont \li QGenericMatrix \li QHash<Key, T> + \li QHostAddress \li QIcon \li QImage + \li QJsonArray + \li QJsonDocument + \li QJsonObject + \li QJsonValue \li QKeySequence + \li QLine + \li QLineF \li QList<T> + \li QListWidgetItem + \li QLocale \li QMap<Key, T> \li QMargins + \li QMarginsF \li QMatrix4x4 - \li QPair<T1, T2> + \li QModelIndex + \li QModelIndexList + \li QMultiHash<Key + \li QMultiMap<Key + \li QNetworkCacheMetaData + \li QNetworkCacheMetaData::AttributesMap + \li QPageRanges + \li QPainterPath + \li std::pair<T1, T2> \li QPalette \li QPen \li QPicture \li QPixmap \li QPoint + \li QPointF + \li QPolygon + \li QPolygonF \li QQuaternion \li QRect + \li QRectF \li QRegularExpression \li QRegion + \li QSet \li QSize + \li QSizeF + \li QSizePolicy + \li QStandardItem \li QString + \li QTableWidgetItem + \li QTextBlockFormat + \li QTextCharFormat + \li QTextFormat + \li QTextFrameFormat + \li QTextLength + \li QTextListFormat + \li QTextTableCellFormat + \li QTimeZone \li QTime \li QTransform + \li QTreeWidgetItem + \li QTypeRevision \li QUrl + \li QUuid \li QVariant \li QVector2D \li QVector3D \li QVector4D + \li QVersionNumber \endlist \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 71e6cf17c6..b787651aba 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -166,3 +166,8 @@ \externalpage https://cmake.org/cmake/help/latest/command/cmake_policy.html \title cmake_policy */ + +/*! + \externalpage https://cmake.org/cmake/help/latest/guide/importing-exporting/index.html#creating-packages + \title Creating CMake packages +*/ diff --git a/src/corelib/doc/src/foreach-keyword.qdoc b/src/corelib/doc/src/foreach-keyword.qdoc index 780be6e09c..6aa21d5880 100644 --- a/src/corelib/doc/src/foreach-keyword.qdoc +++ b/src/corelib/doc/src/foreach-keyword.qdoc @@ -31,7 +31,7 @@ \snippet code/doc_src_containers.cpp 16 - Unless the data type contains a comma (e.g., \c{QPair<int, + Unless the data type contains a comma (e.g., \c{std::pair<int, int>}), the variable used for iteration can be defined within the \c foreach statement: @@ -73,4 +73,18 @@ \c foreach would not. But using \c foreach always copies the container, which is usually not cheap for STL containers. If in doubt, prefer \c foreach for Qt containers, and range based \c for for STL ones. + + You can remove the availability of the Qt's \c foreach loop by + defining the \c{QT_NO_FOREACH} macro. +*/ + +/*! + \macro QT_NO_FOREACH + \since 6.0 + \relates <QtGlobal> + + Defining this macro removes the availability of Qt's \c foreach + loop. + + \sa QT_NO_KEYWORDS */ diff --git a/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc index 4f8203070a..632ddf756f 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc @@ -2,8 +2,11 @@ cmake_minimum_required(VERSION 3.16...3.22) project(MyThings) +# The following CMAKE_INSTALL_*DIR variables are used to initialize their +# QT_DEPLOY_*_DIR counterparts. set(CMAKE_INSTALL_BINDIR "mybindir") set(CMAKE_INSTALL_LIBDIR "mylibdir") +set(CMAKE_INSTALL_LIBEXECDIR "mylibexecdir") find_package(Qt6 REQUIRED COMPONENTS Core) qt_standard_project_setup() diff --git a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc new file mode 100644 index 0000000000..0f46379c45 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc @@ -0,0 +1,20 @@ +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +# Generate a deployment script to be executed at install time +qt_generate_deploy_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + CONTENT " +qt_deploy_runtime_dependencies( + EXECUTABLE \"${executable_path}\" + DEPLOY_TOOL_OPTIONS "${deploy_tool_options_arg}" + GENERATE_QT_CONF + VERBOSE +)") +\endcode diff --git a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc index c5a1a40356..27e04b5b08 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc @@ -1,2 +1,6 @@ This variable is defined by the script named by \l QT_DEPLOY_SUPPORT. It should only be used as part of deployment during installation or a post-build rule. + +\note This is a low-level deployment API variable, and should only be used in +advanced use-cases that are not covered by the higher-level API commands, like +\l{qt_generate_deploy_app_script}. diff --git a/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc new file mode 100644 index 0000000000..64c6b3e49f --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc @@ -0,0 +1,16 @@ +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +qt_generate_deploy_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + NO_UNSUPPORTED_PLATFORM_ERROR + DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg} +) +install(SCRIPT ${deploy_script}) +\endcode diff --git a/src/corelib/doc/src/includes/models.qdocinc b/src/corelib/doc/src/includes/models.qdocinc new file mode 100644 index 0000000000..cf840b1cae --- /dev/null +++ b/src/corelib/doc/src/includes/models.qdocinc @@ -0,0 +1,14 @@ +//! [thread-safety-section1] +\section1 Thread safety + +Being a \l {Accessing QObject Subclasses from Other Threads}{subclass of +QObject}, \1 is not \l {Reentrancy and Thread-Safety}{thread-safe}. Any \1 +model-related API should only be called from the thread the model object lives +in. If the \1 is connected with a view, that means the GUI thread, as that is +where the view lives, and it will call into the model from the GUI thread. +Using a background thread to populate or modify the contents of a model is +possible, but requires care, as the background thread cannot call any +model-related API directly. Instead, you should queue the updates and apply +them in the main thread. This can be done with \l {Signals and Slots Across +Threads}{queued connections}. +//! [thread-safety-section1] diff --git a/src/corelib/doc/src/includes/qstring.qdocinc b/src/corelib/doc/src/includes/qstring.qdocinc index dade4f0af0..66ed12dff3 100644 --- a/src/corelib/doc/src/includes/qstring.qdocinc +++ b/src/corelib/doc/src/includes/qstring.qdocinc @@ -26,9 +26,9 @@ in this string, searching backward from index position \a from. //! [qstring-local-8-bit-equivalent] On Unix systems this is equivalent to \1(). Note that on Apple systems this function does not take -\c\l{https://developer.apple.com/documentation/foundation/nsstring/1410091-defaultcstringencoding?language=objc} +\l{https://developer.apple.com/documentation/foundation/nsstring/1410091-defaultcstringencoding?language=objc} {NSString.defaultCStringEncoding} or -\c\l{https://developer.apple.com/documentation/corefoundation/1541720-cfstringgetsystemencoding?language=objc} +\l{https://developer.apple.com/documentation/corefoundation/1541720-cfstringgetsystemencoding?language=objc} {CFStringGetSystemEncoding()} into account, as these functions typically return the legacy "Western (Mac OS Roman)" encoding, which should not be used on modern Apple operating systems. diff --git a/src/corelib/doc/src/ipc.qdoc b/src/corelib/doc/src/ipc.qdoc index 1de20f89a2..7ec6f5fa3b 100644 --- a/src/corelib/doc/src/ipc.qdoc +++ b/src/corelib/doc/src/ipc.qdoc @@ -7,6 +7,7 @@ \ingroup groups \ingroup frameworks-technologies \keyword ipc + \ingroup explanations-networkingandconnectivity \brief An overview of Qt's inter-process communication functionality @@ -85,7 +86,7 @@ \keyword ipc \keyword shared memory - \brief Overview of the techniques for sharing memory between processes + \brief Overview of the techniques for sharing memory between processes. Qt provides two techniques to share memory with other processes in the same system: \l{QSharedMemory} and memory-mapped files using \l{QFile}. Memory @@ -273,7 +274,10 @@ file names, in particular those that separate path components (slash and backslash), with the exception of sandboxed applications on Apple operating systems. The following are good examples of cross-platform keys: "myapp", - "org.example.myapp", "org.example.myapp-12345". + "org.example.myapp", "org.example.myapp-12345". Note that it is up to the + caller to prevent oversized keys, and to ensure that the key contains legal + characters on the respective platform. Qt will silently truncate keys that + are too long. \b{Apple sandbox limitations:} if the application is running inside of a sandbox in an Apple operating system, the key must be in a very specific @@ -386,7 +390,7 @@ Qt's own build. For Windows systems, it was always the Windows backend. For Unix systems, it defaulted to the System V backend if the configuration script determined it was available. If it was not available, it fell back - to the POSIX one (since Qt 4.8). The POSIX backend could be explicitly + to the POSIX one. The POSIX backend could be explicitly selected using the \c{-feature-ipc_posix} option to the Qt configure script; if it was enabled, the \c{QT_POSIX_IPC} macro would be defined. @@ -410,7 +414,7 @@ It can be updated to be: \code QSharedMemory shm(QSharedMemory::legacyNativeKey("org.example.myapplication")); - QSystemSempahore sem(QSystemSemaphore::legacyNativeKey("org.example.myapplication")); + QSystemSemaphore sem(QSystemSemaphore::legacyNativeKey("org.example.myapplication")); \endcode If the two applications exchanged native keys, there is no need to update diff --git a/src/corelib/doc/src/jni.qdoc b/src/corelib/doc/src/jni.qdoc new file mode 100644 index 0000000000..d05dd44ff6 --- /dev/null +++ b/src/corelib/doc/src/jni.qdoc @@ -0,0 +1,230 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \namespace QtJniTypes + \inmodule QtCore + \ingroup frameworks-technologies + \keyword JNI + \since 6.8 + + \brief The QtJniTypes namespace declares C++ types that correspond to Java types. + + The \l{Java Native Interface Specification}{Java Native Interface} + framework enables native C or C++ code to call Java APIs, and to register + native C or C++ functions that Java code should be able to call with the + JVM. In Qt, the QJniObject and QJniEnvironment types provide convenient + wrappers for using JNI. + + Since the Java language, similar to C++, supports overloading, functions + need to be specified including their entire signature string. This is + complex, repetitive, and error prone, especially when functions take + several parameters. QJniObject provides variadic template APIs that can + deduce the signature string for a function call at compile time, based on + the C++ types passed into the template. For this to work, the mapping of + those C++ types to their corresponding JNI string needs to be known at + compile time. + + Qt implements this mapping for the standard \l {JNI types}. + By using the Q_DECLARE_JNI_CLASS macro, the mapping can be extended for + arbitrary Java types. + + \sa Q_DECLARE_JNI_CLASS, Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_METHOD +*/ + +/*! + \macro Q_DECLARE_JNI_TYPE(Type, JavaSignature) + \internal + \relates QtJniTypes + \since 6.8 + + Declares a C++ type \a Type in the QtJniTypes namespace that wraps the Java + type \a JavaSignature. The signature needs to start with \c{[L} to indicate + an array of a class, or with \c{L} for classes, and end with a semicolon + \c{;}. + + \code + Q_DECLARE_JNI_TYPE(StringArray, "[Ljava/lang/String;") + \endcode + + \sa Q_DECLARE_JNI_CLASS +*/ + +/*! + \macro Q_DECLARE_JNI_CLASS(Type, JavaSignature) + \relates QtJniTypes + \since 6.8 + + Declares a C++ type \a Type in the QtJniTypes namespace that wraps the Java + class \a JavaSignature. The Java class name in \a JavaSignature needs to be + fully qualified, using \c{/} as the separator. + + \code + Q_DECLARE_JNI_CLASS(File, "java/io/File") + Q_DECLARE_JNI_CLASS(FileWriter, "java/io/FileWriter") + \endcode + + The C++ classes \c{QtJniTypes::File} and \c{QtJniTypes::FileWriter} are + then QJniObject-like types that can be used to instantiate the + corresponding Java class, to call methods, and to pass such instances + through QJniObject variadic template methods with automatic, compile-time + signature deduction. + + \code + using namespace QtJniTypes; + + File file("path/to/file"); // instantiates the java.io.File type in Java + if (file.callMethod<bool>("createNewFile")) { + FileWriter writer(file); // instantiates a java.io.FileWriter that operates on file + writer.callMethod("write", 42); + } + \endcode + + In addition to the QJniObject API, those C++ classes also have a static + \c{registerNativeMethods} member function that can be used like this: + + \code + QtJniTypes::File::registerNativeMethods({ + Q_JNI_NATIVE_METHOD(freeFunction) + }); + \endcode + + \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_METHOD +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD(Method) + \relates QtJniTypes + \since 6.8 + + Declares the free C or C++ function \a Method as a native method. The + method can later be registered with the JNI framework using + QJniEnvironment::registerNativeMethod() with the help of the + Q_JNI_NATIVE_METHOD macro. + +//! [register-free-function] + \code + // C++ side + + Q_DECLARE_JNI_CLASS(MyJavaType, "my/java/Type") + + static void nativeFunction(JNIEnv *env, jobject thiz, jlong id) + { + // ... + } + Q_DECLARE_JNI_NATIVE_METHOD(nativeFunction) + + Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) + { + QJniEnvironment env; + env.registerNativeMethods<QtJniTypes::MyJavaType>({ + Q_JNI_NATIVE_METHOD(nativeFunction) + }); + } + + // Java side + public class MyJavaType + { + native public nativeFunction(long id); + } + \endcode +//! [register-free-function] + + \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD(Method, JavaName) + \relates QtJniTypes + \overload + \since 6.8 + + Declares the free C or C++ function \a Method as a native method that's + available in Java as \a JavaName. The method can later be registered with + the JNI framework using QJniEnvironment::registerNativeMethod() with the + help of the Q_JNI_NATIVE_METHOD macro. + + \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method) + \relates QtJniTypes + \since 6.8 + + Declares the C++ static class member function \a Method as a native method. + The method can later be registered with the JNI framework using + QJniEnvironment::registerNativeMethod() with the help of the + Q_JNI_NATIVE_SCOPED_METHOD macro. + +//! [register-scoped-function] + \code + class NativeHandler + { + // ... + private: + static void handleChange(JNIEnv*, jobject, jlong id); + Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(handleChange) + }; + + \dots + QJniEnvironment env; + env.registerNativeMethods<QtJniTypes::MyJavaType>({ + Q_JNI_NATIVE_SCOPED_METHOD(handleChange, NativeHandler) + }); + \endcode +//! [register-scoped-function] + + \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_SCOPED_METHOD +*/ + +/*! + \macro Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(Method, JavaName) + \relates QtJniTypes + \overload + \since 6.8 + + Declares the C++ static class member function \a Method as a native method + that's available in Java as \a JavaName. The method can later be registered + with the JNI framework using QJniEnvironment::registerNativeMethod() with + the help of the Q_JNI_NATIVE_METHOD macro. + + \sa Q_DECLARE_JNI_NATIVE_METHOD, Q_JNI_NATIVE_SCOPED_METHOD +*/ + +/*! + \macro Q_JNI_NATIVE_METHOD(Method) + \relates QtJniTypes + \since 6.8 + + Makes the previously \l{Q_DECLARE_JNI_NATIVE_METHOD}{declared} native + method \a Method available for registration with the JNI framework. Use + this macro when registering the method with JNI using + QJniEnvironment::registerNativeMethod(). + + \code + Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) + { + QJniEnvironment env; + env.registerNativeMethods<QtJniTypes::MyJavaType>({ + Q_JNI_NATIVE_METHOD(nativeFunction) + }); + } + \endcode + + \sa Q_DECLARE_JNI_NATIVE_METHOD +*/ + +/*! + \macro Q_JNI_NATIVE_SCOPED_METHOD(Method, Scope) + \relates QtJniTypes + \since 6.8 + + Makes the previously + \l{Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE}{declared} native method + \a Method in scope \a Scope available for registration with the JNI framework. + Use this macro when registering the method with JNI using + QJniEnvironment::registerNativeMethod(). + + \sa Q_JNI_NATIVE_METHOD, Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE +*/ diff --git a/src/corelib/doc/src/json.qdoc b/src/corelib/doc/src/json.qdoc index 3097075eb9..98ae202cfa 100644 --- a/src/corelib/doc/src/json.qdoc +++ b/src/corelib/doc/src/json.qdoc @@ -6,7 +6,7 @@ \title JSON Support in Qt \ingroup qt-basic-concepts \brief An overview of JSON support in Qt. - + \ingroup explanations-dataprocessingandio \ingroup frameworks-technologies \keyword JSON @@ -73,8 +73,7 @@ A valid JSON document is either an array or an object, so a document always starts with a square or curly bracket. - \sa {JSON Save Game Example} - + \sa {Saving and Loading a Game} \section1 The JSON Classes @@ -82,5 +81,4 @@ \l{Implicit Sharing}{implicitly shared classes}. JSON support in Qt consists of these classes: - */ diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc index d6f96f6579..9b3ea6ae66 100644 --- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -32,7 +32,7 @@ different objects. The \l {Introductory Example} below demonstrates the usage of bindable - properties in C++ code. You can also check \l {Bindable Properties Example} + properties in C++ code. You can also check \l {Bindable Properties} example to see how the bindable properties can help to improve your code. \section1 Introductory Example @@ -256,8 +256,8 @@ Q_PROPERTYs without \c BINDABLE can also be bound and be used in binding expressions, as long as they define a \c NOTIFY signal. You must wrap the property in a \l QBindable using the \c {QBindable(QObject* obj, const char* property)} constructor. Then, the - property can be bound using \c \l QBindable::setBinding() or used in a binding - expression via \c \l QBindable::value(). You must use \c QBindable::value() in binding + property can be bound using \l QBindable::setBinding() or used in a binding + expression via \l QBindable::value(). You must use \c QBindable::value() in binding expressions instead of the normal property \c READ function (or \c MEMBER) to enable dependency tracking if the property is not \c BINDABLE. diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc index 62226ca466..44f574816e 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -5,7 +5,7 @@ \page metaobjects.html \title The Meta-Object System \brief An overview of Qt's meta-object system and introspection capabilities. - + \ingroup explanations-basics \ingroup qt-basic-concepts \keyword meta-object \keyword Meta-Object System @@ -19,8 +19,7 @@ \list 1 \li The \l QObject class provides a base class for objects that can take advantage of the meta-object system. - \li The Q_OBJECT macro inside the private section of the class - declaration is used to enable meta-object features, such as + \li The Q_OBJECT macro is used to enable meta-object features, such as dynamic properties, signals, and slots. \li The \l{moc}{Meta-Object Compiler} (\c moc) supplies each QObject subclass with the necessary code to implement diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index eef2df7028..0e66c8445c 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -5,7 +5,7 @@ \page properties.html \title The Property System \brief An overview of Qt's property system. - + \ingroup explanations-basics \ingroup qt-basic-concepts \keyword Qt's Property System @@ -93,7 +93,7 @@ \li The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., - \l {Qt Designer Manual}{Qt Designer}). Most properties are \c DESIGNABLE + \l {Qt Widgets Designer Manual}{\QD}). Most properties are \c DESIGNABLE (default true). Valid values are true and false. \li The \c SCRIPTABLE attribute indicates whether this property @@ -186,12 +186,11 @@ \section1 A Simple Example - Suppose we have a class MyClass, which is derived from QObject and - which uses the Q_OBJECT macro in its private section. We want to - declare a property in MyClass to keep track of a priority - value. The name of the property will be \e priority, and its type - will be an enumeration type named \e Priority, which is defined in - MyClass. + Suppose we have a class \c MyClass, which is derived from QObject and which + uses the Q_OBJECT macro. We want to declare a property in \c MyClass to keep + track of a priority value. The name of the property will be \c priority, and + its type will be an enumeration type named \c Priority, which is defined in + \c MyClass. We declare the property with the Q_PROPERTY() macro in the private section of the class. The required \c READ function is named \c @@ -200,7 +199,7 @@ System} using the Q_ENUM() macro. Registering an enumeration type makes the enumerator names available for use in calls to QObject::setProperty(). We must also provide our own declarations - for the \c READ and \c WRITE functions. The declaration of MyClass + for the \c READ and \c WRITE functions. The declaration of \c MyClass then might look like this: \snippet code/doc_src_properties.cpp 5 @@ -208,26 +207,29 @@ The \c READ function is const and returns the property type. The \c WRITE function returns void and has exactly one parameter of the property type. The meta-object compiler enforces these - requirements. + requirements. The equality check in the \c WRITE function, while not + mandatory, is good practice as there is no point in notifying and + potentially forcing re-evaluation in other places if nothing has + changed. - Given a pointer to an instance of MyClass or a pointer to a - QObject that is an instance of MyClass, we have two ways to set + Given a pointer to an instance of \c MyClass or a pointer to a + QObject that is an instance of \c MyClass, we have two ways to set its priority property: \snippet code/doc_src_properties.cpp 6 In the example, the enumeration type that is the property type is - declared in MyClass and registered with the \l{Meta-Object System} + declared in \c MyClass and registered with the \l{Meta-Object System} using the Q_ENUM() macro. This makes the enumeration values - available as strings for use as in the call to \l{QObject::}{setProperty()}. Had - the enumeration type been declared in another class, its fully + available as strings for use as in the call to \l{QObject::}{setProperty()}. + Had the enumeration type been declared in another class, its fully qualified name (i.e., OtherClass::Priority) would be required, and that other class would also have to inherit QObject and register the enumeration type there using the Q_ENUM() macro. A similar macro, Q_FLAG(), is also available. Like Q_ENUM(), it registers an enumeration type, but it marks the type as being a - set of \e flags, i.e. values that can be OR'd together. An I/O + set of \e flags, i.e., values that can be OR'd together. An I/O class might have enumeration values \c Read and \c Write and then QObject::setProperty() could accept \c{Read | Write}. Q_FLAG() should be used to register this enumeration type. @@ -274,7 +276,9 @@ Connected to the property system is an additional macro, Q_CLASSINFO(), that can be used to attach additional - \e{name}--\e{value} pairs to a class's meta-object, for example: + \e{name}--\e{value} pairs to a class's meta-object. This is + used for instance to mark a property as the \e default one + in the context of \l{QML Object Types}: \snippet code/doc_src_properties.cpp 7 @@ -296,5 +300,5 @@ and the general tips on implementing and using \l {Qt Bindable Properties}{bindable properties}. - \sa {Qt Bindable Properties} + \sa {Qt Bindable Properties}, {Defining QML Types from C++} */ diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc index 1b427f5775..f0eeb20048 100644 --- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc +++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc @@ -8,7 +8,7 @@ \ingroup qt-basic-concepts \brief An overview of Qt's signals and slots inter-object communication mechanism. - + \ingroup explanations-basics Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by @@ -109,8 +109,7 @@ when the signal is emitted. Signals are automatically generated by the \l moc and must not be - implemented in the \c .cpp file. They can never have return types - (i.e. use \c void). + implemented in the \c .cpp file. A note about arguments: Our experience shows that signals and slots are more reusable if they do not use special types. If @@ -297,8 +296,7 @@ callbacks, you'd have to find five different names and keep track of the types yourself. - \sa QLCDNumber, QObject::connect(), {Digital Clock Example}, - {Tetrix Example} + \sa QLCDNumber, QObject::connect() \section1 Signals And Slots With Default Arguments diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc index 16f76902d4..7c7613c9b8 100644 --- a/src/corelib/doc/src/resource-system.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -17,7 +17,7 @@ Most commonly, the resource files are embedded into your application executable, or in libraries and plugins that are loaded by the application executable. Alternatively, the resource files can also be stored in an - \l{External Resource Files}{exernal resource file}. + \l{External Resource Files}{external resource file}. The resource system is based on tight cooperation between Qt's \l rcc resource compiler, the build system, and the Qt runtime API. @@ -52,7 +52,7 @@ Here's an example \c .qrc file: - \quotefile resource-system/mainwindow.qrc + \quotefile resource-system/application.qrc Each \c <file> element in the XML identifies a file in the application's source tree. The path is resolved relative to the directory containing @@ -102,7 +102,7 @@ variable. If you add a \c .qrc file path to the variable, the listed resource files will be embedded into the generated library or executable: - \snippet resource-system/mainwindow.pro qrc + \snippet resource-system/application.pro qrc This creates a resource of several \c{.png} files, that are addressable like this: \c{":/res/titlebarLeft.png"}. @@ -130,9 +130,6 @@ \snippet resource-system/main.cpp url - See the \l{mainwindows/mainwindow}{Mainwindow} example for an actual - application that uses Qt's resource system to store its icons. - \section1 Advanced Topics \section2 Prefixes diff --git a/src/corelib/doc/src/timers.qdoc b/src/corelib/doc/src/timers.qdoc index 1d5a48af3d..dc205a47b9 100644 --- a/src/corelib/doc/src/timers.qdoc +++ b/src/corelib/doc/src/timers.qdoc @@ -6,17 +6,17 @@ \title Timers \brief How to use Qt timers in your application. - \ingroup best-practices + \ingroup how-to QObject, the base class of all Qt objects, provides the basic timer support in Qt. With QObject::startTimer(), you start a timer with an interval in milliseconds as argument. The function - returns a unique integer timer ID. The timer will now fire at + returns a unique integral timer ID. The timer will then fire at regular intervals until you explicitly call QObject::killTimer() - with the timer ID. + with that timer ID. For this mechanism to work, the application must run in an event - loop. You start an event loop with QApplication::exec(). When a + loop. You cat start an event loop with QApplication::exec(). When a timer fires, the application sends a QTimerEvent, and the flow of control leaves the event loop until the timer event is processed. This implies that a timer cannot fire while your application is @@ -31,69 +31,65 @@ stop all timers in the object's thread; it is not possible to start timers for objects in another thread. - The upper limit for the interval value is determined by the number - of milliseconds that can be specified in a signed integer - (in practice, this is a period of just over 24 days). The accuracy - depends on the underlying operating system. Windows 2000 has 15 - millisecond accuracy; other systems that we have tested can handle - 1 millisecond intervals. - - The main API for the timer functionality is QTimer. That class - provides regular timers that emit a signal when the timer fires, and - inherits QObject so that it fits well into the ownership structure - of most Qt programs. The normal way of using it is like this: - - \snippet timers/timers.cpp 0 - \snippet timers/timers.cpp 1 - \snippet timers/timers.cpp 2 - - The QTimer object is made into a child of \c this object so that, - when \c this object is deleted, the timer is deleted too. - Next, its \l{QTimer::}{timeout()} signal is connected to the slot - that will do the work, it is started with a value of 1000 - milliseconds, indicating that it will time out every second. - - QTimer also provides a static function for single-shot timers. + The main API for the timer functionality was \l QTimer. QTimer stores + the interval in a signed integer, which limits the maximum interval it + supports to the number of milliseconds that can fit in a signed integer + (in practice, this is a period of around 24 days). + + Qt 6.8 introduced the \l QChronoTimer class to replace QTimer. QChronoTimer + stores the interval as \c std::chrono::nanoseconds, which means that + the maximum interval it supports is around 292 years. This mitigates + the chances of integer overflow that QTimer had if the interval was more + than \c{std::numeric_limits<int>::max()}. + + The accuracy of the timers depends on the underlying operating system. + Windows 2000 has 15ms accuracy; other systems that we have tested can + handle 1ms intervals. + + QChronoTimer provides regular timers that emit a signal when the timer + fires, and inherits from QObject so that it fits well into the ownership + structure of most Qt programs. The normal way of using it is like this: + + \snippet timers/timers.cpp timer-interval-in-ctor + \snippet timers/timers.cpp timer-setinterval + + The QChronoTimer object is made into a child of the \c this object so + that, when \c this is destroyed, the timer is destroyed too. Next, the + \l{QChronoTimer::}{timeout()} signal is connected to the slot that will + do the work, the timer interval can be either passed to the constructor, + or set later on with setInterval(). + + QChronoTimer also provides static functions for single-shot timers. For example: - \snippet timers/timers.cpp 3 + \snippet timers/timers.cpp qchronotimer-singleshot - 200 milliseconds (0.2 seconds) after this line of code is - executed, the \c updateCaption() slot will be called. + 200ms after this line of code is executed, the \c updateCaption() slot + will be called. - For QTimer to work, you must have an event loop in your - application; that is, you must call QCoreApplication::exec() - somewhere. Timer events will be delivered only while the event - loop is running. + For QChronoTimer to work, you must have an event loop in your application; + that is, you must call QCoreApplication::exec() somewhere. Timer events + will be delivered only while the event loop is running. - In multithreaded applications, you can use QTimer in any thread - that has an event loop. To start an event loop from a non-GUI - thread, use QThread::exec(). Qt uses the timer's - \l{QObject::thread()}{thread affinity} to determine which thread - will emit the \l{QTimer::}{timeout()} signal. Because of this, you - must start and stop the timer in its thread; it is not possible to - start a timer from another thread. - - The \l{widgets/analogclock}{Analog Clock} example shows how to use - QTimer to redraw a widget at regular intervals. From \c{AnalogClock}'s - implementation: - - \snippet timers/analogclock.cpp 0 - \snippet timers/analogclock.cpp 2 - \snippet timers/analogclock.cpp 3 - \snippet timers/analogclock.cpp 4 - \snippet timers/analogclock.cpp 5 - \snippet timers/analogclock.cpp 6 - \dots - \snippet timers/analogclock.cpp 7 - - Every second, QTimer will call the QWidget::update() slot to + In multithreaded applications, you can use QChronoTimer in any thread + that has an event loop. To start an event loop from a non-GUI thread, use + QThread::exec(). Qt uses the timer's \l{QObject::thread()}{thread affinity} + to determine which thread will emit the \l{QChronoTimer::}{timeout()} + signal. Because of this, you must start and stop the timer in its thread; + it is not possible to start a timer from another thread. + + The \l{widgets/analogclock}{Analog Clock} example shows how to + use QChronoTimer to redraw a widget at regular intervals. From + \c{AnalogClock}'s implementation: + + \snippet timers/analogclock.cpp analogclock-qchronotimer + + Every second, QChronoTimer will call the QWidget::update() slot to refresh the clock's display. If you already have a QObject subclass and want an easy optimization, you can use QBasicTimer instead of QTimer. With QBasicTimer, you must reimplement \l{QObject::timerEvent()}{timerEvent()} in your QObject subclass - and handle the timeout there. The \l{widgets/tetrix}{Tetrix} - example shows how to use QBasicTimer. + and handle the timeout there. */ |