diff options
Diffstat (limited to 'src/corelib/doc')
289 files changed, 9311 insertions, 12485 deletions
diff --git a/src/corelib/doc/images/resources.png b/src/corelib/doc/images/resources.png Binary files differdeleted file mode 100644 index eb7af96d77..0000000000 --- a/src/corelib/doc/images/resources.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-button-history.png b/src/corelib/doc/images/statemachine-button-history.png Binary files differdeleted file mode 100644 index 7f51cae3f2..0000000000 --- a/src/corelib/doc/images/statemachine-button-history.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-button-nested.png b/src/corelib/doc/images/statemachine-button-nested.png Binary files differdeleted file mode 100644 index 762ac14df1..0000000000 --- a/src/corelib/doc/images/statemachine-button-nested.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-button.png b/src/corelib/doc/images/statemachine-button.png Binary files differdeleted file mode 100644 index 10102bdf2c..0000000000 --- a/src/corelib/doc/images/statemachine-button.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-customevents.png b/src/corelib/doc/images/statemachine-customevents.png Binary files differdeleted file mode 100644 index 62a42223ef..0000000000 --- a/src/corelib/doc/images/statemachine-customevents.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-customevents2.png b/src/corelib/doc/images/statemachine-customevents2.png Binary files differdeleted file mode 100644 index 57b37ef1dd..0000000000 --- a/src/corelib/doc/images/statemachine-customevents2.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-examples.png b/src/corelib/doc/images/statemachine-examples.png Binary files differdeleted file mode 100644 index b2ec66e19d..0000000000 --- a/src/corelib/doc/images/statemachine-examples.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-finished.png b/src/corelib/doc/images/statemachine-finished.png Binary files differdeleted file mode 100644 index 0ac081d6ba..0000000000 --- a/src/corelib/doc/images/statemachine-finished.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-nonparallel.png b/src/corelib/doc/images/statemachine-nonparallel.png Binary files differdeleted file mode 100644 index f9850a74a6..0000000000 --- a/src/corelib/doc/images/statemachine-nonparallel.png +++ /dev/null diff --git a/src/corelib/doc/images/statemachine-parallel.png b/src/corelib/doc/images/statemachine-parallel.png Binary files differdeleted file mode 100644 index a65c297f5b..0000000000 --- a/src/corelib/doc/images/statemachine-parallel.png +++ /dev/null diff --git a/src/corelib/doc/include/QtCoreDoc b/src/corelib/doc/include/QtCoreDoc new file mode 100644 index 0000000000..5f5490cbc9 --- /dev/null +++ b/src/corelib/doc/include/QtCoreDoc @@ -0,0 +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/include/jni.h b/src/corelib/doc/include/jni.h new file mode 100644 index 0000000000..4eff8636f6 --- /dev/null +++ b/src/corelib/doc/include/jni.h @@ -0,0 +1,29 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only + +#pragma once + +// +// W A R N I N G +// ------------- +// +// This file is not part of the Qt API. It exists purely as an +// implementation detail. This header file may change from version to +// version without notice, or even be removed. +// +// We mean it. +// + +// Dummy declarations for generating docs on non-Android platforms +#if !defined(Q_OS_ANDROID) && defined(Q_QDOC) +typedef struct {} JNIEnv; +typedef struct {} JNINativeMethod; +struct _jclass; +typedef _jclass* jclass; +struct _jobject; +typedef _jobject* jobject; +typedef int jint; +typedef int jmethodID; +typedef int jfieldID; +typedef void* JavaVM; +#endif diff --git a/src/corelib/doc/qtcore.qdocconf b/src/corelib/doc/qtcore.qdocconf index 28b926b732..4ed46ae6dd 100644 --- a/src/corelib/doc/qtcore.qdocconf +++ b/src/corelib/doc/qtcore.qdocconf @@ -5,6 +5,9 @@ project = QtCore description = Qt Core Reference Documentation version = $QT_VERSION +moduleheader = QtCoreDoc +includepaths += ./include + examplesinstallpath = corelib qhp.projects = QtCore @@ -15,9 +18,6 @@ qhp.QtCore.virtualFolder = qtcore qhp.QtCore.indexTitle = Qt Core qhp.QtCore.indexRoot = -qhp.QtCore.filterAttributes = qtcore $QT_VERSION qtrefdoc -qhp.QtCore.customFilters.Qt.name = QtCore $QT_VERSION -qhp.QtCore.customFilters.Qt.filterAttributes = qtcore $QT_VERSION qhp.QtCore.subprojects = classes qhp.QtCore.subprojects.classes.title = C++ Classes qhp.QtCore.subprojects.classes.indexTitle = Qt Core C++ Classes @@ -26,11 +26,16 @@ qhp.QtCore.subprojects.classes.sortPages = true tagfile = ../../../doc/qtcore/qtcore.tags -depends += activeqt qtdbus qtgui qtwidgets qtnetwork qtdoc qtmacextras qtquick qtlinguist qtdesigner qtconcurrent qtxml qmake qtwinextras qtqml qtcmake +# Make QtCore depend on all doc modules; this ensures complete inheritance +# information for classes +depends = * headerdirs += .. -sourcedirs += .. +sourcedirs += .. \ + ../../tools/androiddeployqt \ + ../../android/templates \ + src/includes exampledirs += \ ../ \ @@ -38,7 +43,8 @@ exampledirs += \ ../../../examples/corelib \ ../../../examples/network/dnslookup \ ../../../examples/widgets/tools \ - ../../../tests/auto/corelib/thread/qpromise/ + ../../../tests/auto/corelib/thread/qpromise \ + ../../tools/androiddeployqt imagedirs += images @@ -46,11 +52,19 @@ excludedirs += snippets excludefiles += ../../../examples/widgets/tools/customcompleter/doc/src/customcompleter.qdoc +defines += QT_BUILD_CORE_LIB + # Included in qttestlib.qdocconf instead excludefiles += ../kernel/qtestsupport_core.cpp -manifestmeta.highlighted.names = "QtCore/JSON Save Game Example" \ - "QtCore/Local Fortune*" - navigation.landingpage = "Qt Core" navigation.cppclassespage = "Qt Core C++ Classes" + +# 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/buffer/buffer.cpp b/src/corelib/doc/snippets/buffer/buffer.cpp index 66747aad39..160c0327c3 100644 --- a/src/corelib/doc/snippets/buffer/buffer.cpp +++ b/src/corelib/doc/snippets/buffer/buffer.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QBuffer> diff --git a/src/corelib/doc/snippets/cmake-macros/deployment.cmake b/src/corelib/doc/snippets/cmake-macros/deployment.cmake new file mode 100644 index 0000000000..ef7aa726c0 --- /dev/null +++ b/src/corelib/doc/snippets/cmake-macros/deployment.cmake @@ -0,0 +1,27 @@ +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#! [qt_generate_deploy_script_example] +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +install(TARGETS MyApp + BUNDLE DESTINATION . + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) + +qt_generate_deploy_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + CONTENT " +qt_deploy_runtime_dependencies( + EXECUTABLE $<TARGET_FILE_NAME:MyApp> +) +") +install(SCRIPT ${deploy_script}) +#! [qt_generate_deploy_script_example] diff --git a/src/corelib/doc/snippets/cmake-macros/examples.cmake b/src/corelib/doc/snippets/cmake-macros/examples.cmake index 913b39cb4f..09b7470962 100644 --- a/src/corelib/doc/snippets/cmake-macros/examples.cmake +++ b/src/corelib/doc/snippets/cmake-macros/examples.cmake @@ -1,75 +1,106 @@ -#! [qt5_wrap_cpp] -set(SOURCES myapp.cpp main.cpp) -qt5_wrap_cpp(SOURCES myapp.h) -add_executable(myapp ${SOURCES}) -#! [qt5_wrap_cpp] +# Copyright (C) 2022 The Qt Company Ltd. +# 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) -add_executable(myapp ${SOURCES}) -#! [qt_wrap_cpp] +qt_add_executable(myapp ${SOURCES}) +#! [qt_wrap_cpp_1] -#! [qt5_add_resources] -set(SOURCES main.cpp) -qt5_add_resources(SOURCES example.qrc) -add_executable(myapp ${SOURCES}) -#! [qt5_add_resources] +#! [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) qt_add_resources(SOURCES example.qrc) -add_executable(myapp ${SOURCES}) +qt_add_executable(myapp ${SOURCES}) #! [qt_add_resources] -#! [qt5_add_big_resources] -set(SOURCES main.cpp) -qt5_add_big_resources(SOURCES big_resource.qrc) -add_executable(myapp ${SOURCES}) -#! [qt5_add_big_resources] +#! [qt_add_resources_target] +qt_add_executable(myapp main.cpp) +qt_add_resources(myapp "images" + PREFIX "/images" + FILES image1.png image2.png) +#! [qt_add_resources_target] #! [qt_add_big_resources] set(SOURCES main.cpp) qt_add_big_resources(SOURCES big_resource.qrc) -add_executable(myapp ${SOURCES}) -#! [qt_add_big_resources] -#! [qt5_add_binary_resources] -qt5_add_binary_resources(resources project.qrc OPTIONS -no-compress) -add_dependencies(myapp resources) -#! [qt5_add_binary_resources] +# Have big_resource.qrc treated as a source file by Qt Creator +list(APPEND SOURCES big_resource.qrc) +set_property(SOURCE big_resource.qrc PROPERTY SKIP_AUTORCC ON) + +qt_add_executable(myapp ${SOURCES}) +#! [qt_add_big_resources] #! [qt_add_binary_resources] qt_add_binary_resources(resources project.qrc OPTIONS -no-compress) add_dependencies(myapp resources) #! [qt_add_binary_resources] -#! [qt5_generate_moc] -qt5_generate_moc(main.cpp main.moc TARGET myapp) -#! [qt5_generate_moc] - #! [qt_generate_moc] qt_generate_moc(main.cpp main.moc TARGET myapp) #! [qt_generate_moc] -#! [qt5_import_plugins] -add_executable(myapp main.cpp) -target_link_libraries(myapp Qt5::Gui Qt5::Sql) -qt5_import_plugins(myapp - INCLUDE Qt5::QCocoaIntegrationPlugin - EXCLUDE Qt5::QMinimalIntegrationPlugin - INCLUDE_BY_TYPE imageformats Qt5::QGifPlugin Qt5::QJpegPlugin - EXCLUDE_BY_TYPE sqldrivers -) -#! [qt5_import_plugins] - #! [qt_import_plugins] -add_executable(myapp main.cpp) +qt_add_executable(myapp main.cpp) target_link_libraries(myapp Qt::Gui Qt::Sql) qt_import_plugins(myapp INCLUDE Qt::QCocoaIntegrationPlugin EXCLUDE Qt::QMinimalIntegrationPlugin - INCLUDE_BY_TYPE imageformats Qt5::QGifPlugin Qt5::QJpegPlugin + INCLUDE_BY_TYPE imageformats Qt::QGifPlugin Qt::QJpegPlugin EXCLUDE_BY_TYPE sqldrivers ) #! [qt_import_plugins] + +#! [qt_add_executable_simple] +qt_add_executable(simpleapp main.cpp) +#! [qt_add_executable_simple] + +#! [qt_add_executable_deferred] +qt_add_executable(complexapp MANUAL_FINALIZATION complex.cpp) +set_target_properties(complexapp PROPERTIES OUTPUT_NAME Complexify) +qt_finalize_target(complexapp) +#! [qt_add_executable_deferred] + +#! [qt_android_deploy_basic] +qt_android_generate_deployment_settings(myapp) +qt_android_add_apk_target(myapp) +#! [qt_android_deploy_basic] + +#! [qt_finalize_project_manual] +cmake_minimum_required(VERSIONS 3.16) + +project(MyProject LANGUAGES CXX) + +find_package(Qt6 REQUIRED COMPONENTS Core) + +qt_add_executable(MyApp main.cpp) +add_subdirectory(mylib) + +qt_finalize_project() +#! [qt_finalize_project_manual] 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 aa8a72be8a..b568462492 100644 --- a/src/corelib/doc/snippets/code/doc_src_containers.cpp +++ b/src/corelib/doc/snippets/code/doc_src_containers.cpp @@ -1,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 @@ -63,14 +18,34 @@ private: }; //! [0] +//! [range_for] +QList<QString> list = {"A", "B", "C", "D"}; +for (const auto &item : list) { + ... +} +//! [range_for] + +//! [range_for_as_const] +QList<QString> list = {"A", "B", "C", "D"}; +for (const auto &item : std::as_const(list)) { + ... +} +//! [range_for_as_const] + +//! [index] +QList<QString> list = {"A", "B", "C", "D"}; +for (qsizetype i = 0; i < list.size(); ++i) { + const auto &item = list.at(i); + ... +} +//! [index] //! [1] -QList<QString> list; -list << "A" << "B" << "C" << "D"; +QList<QString> list = {"A", "B", "C", "D"}; QListIterator<QString> i(list); while (i.hasNext()) - qDebug() << i.next(); + QString s = i.next(); //! [1] @@ -78,7 +53,7 @@ while (i.hasNext()) QListIterator<QString> i(list); i.toBack(); while (i.hasPrevious()) - qDebug() << i.previous(); + QString s = i.previous(); //! [2] @@ -118,11 +93,12 @@ while (i.hasNext()) //! [7] -QMap<QString, QString> map; -map.insert("Paris", "France"); -map.insert("Guatemala City", "Guatemala"); -map.insert("Mexico City", "Mexico"); -map.insert("Moscow", "Russia"); +QMap<QString, QString> map = { + {"Paris", "France"}, + {"Guatemala City", "Guatemala"}, + {"Mexico City", "Mexico"}, + {"Moscow", "Russia"} +}; ... QMutableMapIterator<QString, QString> i(map); @@ -153,28 +129,23 @@ while (i.findNext(widget)) //! [10] -QList<QString> list; -list << "A" << "B" << "C" << "D"; +QList<QString> list = {"A", "B", "C", "D"}; -QList<QString>::iterator i; -for (i = list.begin(); i != list.end(); ++i) +for (auto i = list.begin(), end = list.end(); i != end; ++i) *i = (*i).toLower(); //! [10] //! [11] -QList<QString> list; -list << "A" << "B" << "C" << "D"; +QList<QString> list = {"A", "B", "C", "D"}; -QList<QString>::reverse_iterator i; -for (i = list.rbegin(); i != list.rend(); ++i) +for (auto i = list.rbegin(), rend = list.rend(); i != rend; ++i) *i = i->toLower(); //! [11] //! [12] -QList<QString>::const_iterator i; -for (i = list.constBegin(); i != list.constEnd(); ++i) +for (auto i = list.cbegin(), end = list.cend(); i != end; ++i) qDebug() << *i; //! [12] @@ -182,8 +153,7 @@ for (i = list.constBegin(); i != list.constEnd(); ++i) //! [13] QMap<int, int> map; ... -QMap<int, int>::const_iterator i; -for (i = map.constBegin(); i != map.constEnd(); ++i) +for (auto i = map.cbegin(), end = map.cend(); i != end; ++i) qDebug() << i.key() << ':' << i.value(); //! [13] @@ -191,13 +161,11 @@ for (i = map.constBegin(); i != map.constEnd(); ++i) //! [14] // RIGHT const QList<int> sizes = splitter->sizes(); -QList<int>::const_iterator i; -for (i = sizes.begin(); i != sizes.end(); ++i) +for (auto i = sizes.begin(), end = sizes.end(); i != end; ++i) ... // WRONG -QList<int>::const_iterator i; -for (i = splitter->sizes().begin(); +for (auto i = splitter->sizes().begin(); i != splitter->sizes().end(); ++i) ... //! [14] @@ -216,8 +184,10 @@ foreach (str, values) QList<QString> values; ... QListIterator<QString> i(values); -while (i.hasNext()) - qDebug() << i.next(); +while (i.hasNext()) { + QString s = i.next(); + qDebug() << s; +} //! [16] @@ -258,25 +228,23 @@ foreach (const QString &str, map.uniqueKeys()) { //! [20] -//! [21] -forever { - ... -} -//! [21] - - //! [22] CONFIG += no_keywords //! [22] +//! [cmake_no_keywords] +target_compile_definitions(my_app PRIVATE QT_NO_KEYWORDS) +//! [cmake_no_keywords] + + //! [23] QString onlyLetters(const QString &in) { QString out; - for (int j = 0; j < in.size(); ++j) { - if (in[j].isLetter()) - out += in[j]; + for (qsizetype j = 0; j < in.size(); ++j) { + if (in.at(j).isLetter()) + out += in.at(j); } return out; } @@ -313,9 +281,30 @@ int j = *i; // Undefined behavior! //! [24] //! [25] -QList<int> list { 1, 2, 3, 4, 4, 5 }; -QSet<int> set(list.begin(), list.end()); +QList<int> list = {1, 2, 3, 4, 4, 5}; +QSet<int> set(list.cbegin(), list.cend()); /* - Will generate a QSet containing 1, 2, 4, 5. + Will generate a QSet containing 1, 2, 3, 4, 5. */ //! [25] + +//! [26] +QList<int> list = {2, 3, 1}; + +std::sort(list.begin(), list.end()); +/* + Sort the list, now contains { 1, 2, 3 } +*/ + +std::reverse(list.begin(), list.end()); +/* + Reverse the list, now contains { 3, 2, 1 } +*/ + +int even_elements = + std::count_if(list.begin(), list.end(), [](int element) { return (element % 2 == 0); }); +/* + Count how many elements that are even numbers, 1 +*/ + +//! [26] diff --git a/src/corelib/doc/snippets/code/doc_src_groups.cpp b/src/corelib/doc/snippets/code/doc_src_groups.cpp index 2b8ed39447..a0901904db 100644 --- a/src/corelib/doc/snippets/code/doc_src_groups.cpp +++ b/src/corelib/doc/snippets/code/doc_src_groups.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void QPen::setStyle(Qt::PenStyle style) diff --git a/src/corelib/doc/snippets/code/doc_src_objecttrees.cpp b/src/corelib/doc/snippets/code/doc_src_objecttrees.cpp index 849b628e0c..b7c71ccb6b 100644 --- a/src/corelib/doc/snippets/code/doc_src_objecttrees.cpp +++ b/src/corelib/doc/snippets/code/doc_src_objecttrees.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //![0] int main() diff --git a/src/corelib/doc/snippets/code/doc_src_properties.cpp b/src/corelib/doc/snippets/code/doc_src_properties.cpp index e026a47e23..190a843710 100644 --- a/src/corelib/doc/snippets/code/doc_src_properties.cpp +++ b/src/corelib/doc/snippets/code/doc_src_properties.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] Q_PROPERTY(type name @@ -59,9 +12,10 @@ Q_PROPERTY(type name [SCRIPTABLE bool] [STORED bool] [USER bool] + [BINDABLE bindableProperty] [CONSTANT] - [FINAL]) - [REQUIRED] + [FINAL] + [REQUIRED]) //! [0] @@ -106,7 +60,7 @@ class MyClass : public QObject Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY priorityChanged) public: - MyClass(QObject *parent = 0); + MyClass(QObject *parent = nullptr); ~MyClass(); enum Priority { High, Low, VeryHigh, VeryLow }; @@ -114,6 +68,9 @@ public: void setPriority(Priority priority) { + if (m_priority == priority) + return; + m_priority = priority; emit priorityChanged(priority); } @@ -139,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 58f6b196b4..f2b94a7416 100644 --- a/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qalgorithms.cpp @@ -1,364 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -QStringList list; -list << "one" << "two" << "three"; - -qFill(list.begin(), list.end(), "eleven"); -// list: [ "eleven", "eleven", "eleven" ] -//! [0] - +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [1] -qFill(list.begin() + 1, list.end(), "six"); -// list: [ "eleven", "six", "six" ] -//! [1] - - -//! [2] -QChar resolveEntity(const QString &entity) -{ - static const QLatin1String name_table[] = { - "AElig", "Aacute", ..., "zwnj" - }; - static const ushort value_table[] = { - 0x0061, 0x00c1, ..., 0x200c - }; - int N = sizeof(name_table) / sizeof(name_table[0]); - - const QLatin1String *name = qBinaryFind(name_table, name_table + N, - entity); - int index = name - name_table; - if (index == N) - return QChar(); - - return QChar(value_table[index]); -} -//! [2] - - -//! [3] -QChar resolveEntity(const QString &entity) -{ - static QMap<QString, int> entityMap; - - if (!entityMap) { - entityMap.insert("AElig", 0x0061); - entityMap.insert("Aacute", 0x00c1); - ... - entityMap.insert("zwnj", 0x200c); - } - return QChar(entityMap.value(entity)); -} -//! [3] - - -//! [4] -QStringList list; -list << "one" << "two" << "three"; - -QList<QString> list1(3); -qCopy(list.begin(), list.end(), list1.begin()); -// list1: [ "one", "two", "three" ] - -QList<QString> list2(8); -qCopy(list.begin(), list.end(), list2.begin() + 2); -// list2: [ "", "", "one", "two", "three", "", "", "" ] -//! [4] - - -//! [5] -QStringList list; -list << "one" << "two" << "three"; - -QList<QString> backList(5); -qCopyBackward(list.begin(), list.end(), backList.end()); -// backList: [ "", "", "one", "two", "three" ] -//! [5] - - -//! [6] -QStringList listLeft; -listLeft << "one" << "two" << "three"; - -QList<QString> listRight(3); -listRight[0] = "one"; -listRight[1] = "two"; -listRight[2] = "three"; - -bool ret1 = qEqual(listLeft.begin(), listLeft.end(), listRight.begin()); -// ret1 == true - -listRight[2] = "seven"; -bool ret2 = qEqual(listLeft.begin(), listLeft.end(), listRight.begin()); -// ret2 == false -//! [6] - - -//! [7] -QStringList list; -list << "one" << "two" << "three"; - -qFill(list.begin(), list.end(), "eleven"); -// list: [ "eleven", "eleven", "eleven" ] - -qFill(list.begin() + 1, list.end(), "six"); -// list: [ "eleven", "six", "six" ] -//! [7] - - -//! [8] -QStringList list; -list << "one" << "two" << "three"; - -QStringList::iterator i1 = qFind(list.begin(), list.end(), "two"); -// i1 == list.begin() + 1 - -QStringList::iterator i2 = qFind(list.begin(), list.end(), "seventy"); -// i2 == list.end() -//! [8] - - -//! [9] -QList<int> list; -list << 3 << 3 << 6 << 6 << 6 << 8; - -int countOf6 = 0; -qCount(list.begin(), list.end(), 6, countOf6); -// countOf6 == 3 - -int countOf7 = 0; -qCount(list.begin(), list.end(), 7, countOf7); -// countOf7 == 0 -//! [9] - - -//! [10] -double pi = 3.14; -double e = 2.71; - -qSwap(pi, e); -// pi == 2.71, e == 3.14 -//! [10] - - -//! [11] -QList<int> list; -list << 33 << 12 << 68 << 6 << 12; -qSort(list.begin(), list.end()); -// list: [ 6, 12, 12, 33, 68 ] -//! [11] - - -//! [12] -bool caseInsensitiveLessThan(const QString &s1, const QString &s2) -{ - return s1.toLower() < s2.toLower(); -} - -int doSomething() -{ - QStringList list; - list << "AlPha" << "beTA" << "gamma" << "DELTA"; - qSort(list.begin(), list.end(), caseInsensitiveLessThan); - // list: [ "AlPha", "beTA", "DELTA", "gamma" ] -} -//! [12] - - -//! [13] -QList<int> list; -list << 33 << 12 << 68 << 6 << 12; -qSort(list.begin(), list.end(), qGreater<int>()); -// list: [ 68, 33, 12, 12, 6 ] -//! [13] - - -//! [14] -QStringList list; -list << "AlPha" << "beTA" << "gamma" << "DELTA"; - -QMap<QString, QString> map; -foreach (const QString &str, list) - map.insert(str.toLower(), str); - -list = map.values(); -//! [14] - - -//! [15] -QList<int> list; -list << 33 << 12 << 68 << 6 << 12; -qStableSort(list.begin(), list.end()); -// list: [ 6, 12, 12, 33, 68 ] -//! [15] - - -//! [16] -bool caseInsensitiveLessThan(const QString &s1, const QString &s2) -{ - return s1.toLower() < s2.toLower(); -} - -int doSomething() -{ - QStringList list; - list << "AlPha" << "beTA" << "gamma" << "DELTA"; - qStableSort(list.begin(), list.end(), caseInsensitiveLessThan); - // list: [ "AlPha", "beTA", "DELTA", "gamma" ] -} -//! [16] - - -//! [17] -QList<int> list; -list << 33 << 12 << 68 << 6 << 12; -qStableSort(list.begin(), list.end(), qGreater<int>()); -// list: [ 68, 33, 12, 12, 6 ] -//! [17] - - -//! [18] -QList<int> list; -list << 3 << 3 << 6 << 6 << 6 << 8; - -QList<int>::iterator i = qLowerBound(list.begin(), list.end(), 5); -list.insert(i, 5); -// list: [ 3, 3, 5, 6, 6, 6, 8 ] - -i = qLowerBound(list.begin(), list.end(), 12); -list.insert(i, 12); -// list: [ 3, 3, 5, 6, 6, 6, 8, 12 ] -//! [18] - - -//! [19] -QList<int> list; -list << 3 << 3 << 6 << 6 << 6 << 8; -QList<int>::iterator begin6 = - qLowerBound(list.begin(), list.end(), 6); -QList<int>::iterator end6 = - qUpperBound(begin6, list.end(), 6); - -QList<int>::iterator i = begin6; -while (i != end6) { - *i = 7; - ++i; -} -// list: [ 3, 3, 7, 7, 7, 8 ] -//! [19] - - -//! [20] -QList<int> list; -list << 3 << 3 << 6 << 6 << 6 << 8; - -QList<int>::iterator i = qUpperBound(list.begin(), list.end(), 5); -list.insert(i, 5); -// list: [ 3, 3, 5, 6, 6, 6, 8 ] - -i = qUpperBound(list.begin(), list.end(), 12); -list.insert(i, 12); -// list: [ 3, 3, 5, 6, 6, 6, 8, 12 ] -//! [20] - - -//! [21] -QList<int> list; -list << 3 << 3 << 6 << 6 << 6 << 8; -QList<int>::iterator begin6 = - qLowerBound(list.begin(), list.end(), 6); -QList<int>::iterator end6 = - qUpperBound(list.begin(), list.end(), 6); - -QList<int>::iterator i = begin6; -while (i != end6) { - *i = 7; - ++i; -} -// list: [ 3, 3, 7, 7, 7, 8 ] -//! [21] - - -//! [22] -QList<int> list; -list << 3 << 3 << 6 << 6 << 6 << 8; - -QList<int>::iterator i = - qBinaryFind(list.begin(), list.end(), 6); -// i == list.begin() + 2 (or 3 or 4) -//! [22] - - -//! [23] QList<Employee *> list; list.append(new Employee("Blackpool", "Stephen")); list.append(new Employee("Twist", "Oliver")); qDeleteAll(list.begin(), list.end()); list.clear(); -//! [23] - - -//! [24] -QList<int> list; -list << 33 << 12 << 68 << 6 << 12; -qSort(list.begin(), list.end(), qLess<int>()); -// list: [ 6, 12, 12, 33, 68 ] -//! [24] - - -//! [25] -QList<int> list; -list << 33 << 12 << 68 << 6 << 12; -qSort(list.begin(), list.end(), qGreater<int>()); -// list: [ 68, 33, 12, 12, 6 ] -//! [25] +//! [1] diff --git a/src/corelib/doc/snippets/code/doc_src_qcache.cpp b/src/corelib/doc/snippets/code/doc_src_qcache.cpp index 757a72b521..a15a802760 100644 --- a/src/corelib/doc/snippets/code/doc_src_qcache.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qcache.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QCache<int, Employee> cache; diff --git a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp index ed0cf9e329..0d921b87e6 100644 --- a/src/corelib/doc/snippets/code/doc_src_qiterator.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qiterator.cpp @@ -1,59 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QList<float> list; ... QListIterator<float> i(list); while (i.hasNext()) - qDebug() << i.next(); + float f = i.next(); //! [0] @@ -61,7 +14,7 @@ while (i.hasNext()) QListIterator<float> i(list); i.toBack(); while (i.hasPrevious()) - qDebug() << i.previous(); + float f = i.previous(); //! [1] //! [6] @@ -69,24 +22,15 @@ QSet<QString> set; ... QSetIterator<QString> i(set); while (i.hasNext()) - qDebug() << i.next(); + float f = i.next(); //! [6] - -//! [7] -QSetIterator<QString> i(set); -i.toBack(); -while (i.hasPrevious()) - qDebug() << i.previous(); -//! [7] - - //! [8] QList<float> list; ... QMutableListIterator<float> i(list); while (i.hasNext()) - qDebug() << i.next(); + float f = i.next(); //! [8] @@ -94,7 +38,7 @@ while (i.hasNext()) QMutableListIterator<float> i(list); i.toBack(); while (i.hasPrevious()) - qDebug() << i.previous(); + float f = i.previous(); //! [9] @@ -115,18 +59,9 @@ QSet<float> set; ... QMutableSetIterator<float> i(set); while (i.hasNext()) - qDebug() << i.next(); + float f = i.next(); //! [17] - -//! [18] -QMutableSetIterator<float> i(set); -i.toBack(); -while (i.hasPrevious()) - qDebug() << i.previous(); -//! [18] - - //! [19] QMutableListIterator<int> i(list); while (i.hasNext()) { @@ -183,6 +118,35 @@ while (i.findNext(widget)) { } //! [28] +//! [26multi] +QMultiMap<int, QWidget *> multimap; +... +QMultiMapIterator<int, QWidget *> i(multimap); +while (i.hasNext()) { + i.next(); + qDebug() << i.key() << ": " << i.value(); +} +//! [26multi] + + +//! [27multi] +QMultiMapIterator<int, QWidget *> i(multimap); +i.toBack(); +while (i.hasPrevious()) { + i.previous(); + qDebug() << i.key() << ": " << i.value(); +} +//! [27multi] + + +//! [28multi] +QMultiMapIterator<int, QWidget *> i(multimap); +while (i.findNext(widget)) { + qDebug() << "Found widget " << widget << " under key " + << i.key(); +} +//! [28multi] + //! [29] QHash<int, QWidget *> hash; @@ -244,6 +208,46 @@ while (i.hasNext()) { //! [35] +//! [32multi] +QMultiMap<int, QWidget *> multimap; +... +QMutableMultiMapIterator<int, QWidget *> i(multimap); +while (i.hasNext()) { + i.next(); + qDebug() << i.key() << ": " << i.value(); +} +//! [32multi] + + +//! [33multi] +QMutableMultiMapIterator<int, QWidget *> i(multimap); +i.toBack(); +while (i.hasPrevious()) { + i.previous(); + qDebug() << i.key() << ": " << i.value(); +} +//! [33multi] + + +//! [34multi] +QMutableMultiMapIterator<int, QWidget *> i(multimap); +while (i.findNext(widget)) { + qDebug() << "Found widget " << widget << " under key " + << i.key(); +} +//! [34multi] + + +//! [35multi] +QMutableMultiMapIterator<QString, QString> i(multimap); +while (i.hasNext()) { + i.next(); + if (i.key() == i.value()) + i.remove(); +} +//! [35multi] + + //! [36] QHash<int, QWidget *> hash; ... diff --git a/src/corelib/doc/snippets/code/doc_src_qnamespace.cpp b/src/corelib/doc/snippets/code/doc_src_qnamespace.cpp index cc9f9f3929..1084585584 100644 --- a/src/corelib/doc/snippets/code/doc_src_qnamespace.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qnamespace.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [1] enum CustomEventPriority diff --git a/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc b/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc index 4d8932f837..6ce29308f1 100644 --- a/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc +++ b/src/corelib/doc/snippets/code/doc_src_qnamespace.qdoc @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// 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_qplugin.cpp b/src/corelib/doc/snippets/code/doc_src_qplugin.cpp index 744f425bbc..3bca27b966 100644 --- a/src/corelib/doc/snippets/code/doc_src_qplugin.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qplugin.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] namespace Foo @@ -69,9 +22,3 @@ class MyInstance : public QObject //! [2] Q_IMPORT_PLUGIN(qjpeg) //! [2] - - -//! [3] -TEMPLATE = app -QTPLUGIN += qjpeg qgif # image formats -//! [3] diff --git a/src/corelib/doc/snippets/code/doc_src_qplugin.pro b/src/corelib/doc/snippets/code/doc_src_qplugin.pro deleted file mode 100644 index 52fb9e3163..0000000000 --- a/src/corelib/doc/snippets/code/doc_src_qplugin.pro +++ /dev/null @@ -1,4 +0,0 @@ -#! [3] -TEMPLATE = app -QTPLUGIN += qjpeg qgif # image formats -#! [3] diff --git a/src/corelib/doc/snippets/code/doc_src_qset.cpp b/src/corelib/doc/snippets/code/doc_src_qset.cpp index 96ef07738b..98a6f336f5 100644 --- a/src/corelib/doc/snippets/code/doc_src_qset.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qset.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QSet<QString> set; @@ -73,24 +26,23 @@ if (!set.contains("ninety-nine")) //! [4] QSetIterator<QWidget *> i(set); -while (i.hasNext()) - qDebug() << i.next(); +while (i.hasNext()) { + QWidget *w = i.next(); + qDebug() << w; +} //! [4] //! [5] -QSet<QWidget *>::const_iterator i = set.constBegin(); -while (i != set.constEnd()) { +for (auto i = set.cbegin(), end = set.cend(); i != end; ++i) qDebug() << *i; - ++i; -} //! [5] //! [6] QSet<QString> set; ... -foreach (const QString &value, set) +for (const auto &value : set) qDebug() << value; //! [6] @@ -104,20 +56,18 @@ for (int i = 0; i < 20000; ++i) //! [8] -QSet<QString> set; -set << "January" << "February" << ... << "December"; +QSet<QString> set = {"January", "February", ... "December"} -QSet<QString>::iterator i; -for (i = set.begin(); i != set.end(); ++i) +// i is a QSet<QString>::iterator +for (auto i = set.begin(), end = set.end(); i != end; ++i) qDebug() << *i; //! [8] //! [9] -QSet<QString> set; -set << "January" << "February" << ... << "December"; +QSet<QString> set = {"January", "February", ... "December"}; -QSet<QString>::iterator i = set.begin(); +auto i = set.begin(); while (i != set.end()) { if ((*i).startsWith('J')) { i = set.erase(i); @@ -139,11 +89,10 @@ if (it != set.end()) //! [11] -QSet<QString> set; -set << "January" << "February" << ... << "December"; +QSet<QString> set = {"January", "February", ... "December"}; -QSet<QString>::const_iterator i; -for (i = set.begin(); i != set.end(); ++i) +// i is QSet<QString>::const_iterator +for (auto i = set.cbegin(), end = set.cend(); i != end; ++i) qDebug() << *i; //! [11] @@ -156,23 +105,3 @@ QSet<QString>::const_iterator it = std::find_if(set.cbegin(), set.cend(), predic if (it != set.constEnd()) cout << "Found Jeanette" << endl; //! [12] - - -//! [13] -QSet<QString> set; -set << "red" << "green" << "blue" << ... << "black"; - -QList<QString> list = set.toList(); -std::sort(list.begin(), list.end()); -//! [13] - - -//! [14] -QStringList list; -list << "Julia" << "Mike" << "Mike" << "Julia" << "Julia"; - -QSet<QString> set = QSet<QString>::fromList(list); -set.contains("Julia"); // returns true -set.contains("Mike"); // returns true -set.size(); // returns 2 -//! [14] diff --git a/src/corelib/doc/snippets/code/doc_src_qvarlengtharray.cpp b/src/corelib/doc/snippets/code/doc_src_qvarlengtharray.cpp index 1cbbffc0e4..080874fc77 100644 --- a/src/corelib/doc/snippets/code/doc_src_qvarlengtharray.cpp +++ b/src/corelib/doc/snippets/code/doc_src_qvarlengtharray.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] int myfunc(int n) diff --git a/src/corelib/doc/snippets/code/doc_src_resources.cpp b/src/corelib/doc/snippets/code/doc_src_resources.cpp index b3c556d09a..04ecf810ec 100644 --- a/src/corelib/doc/snippets/code/doc_src_resources.cpp +++ b/src/corelib/doc/snippets/code/doc_src_resources.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [4] QResource::registerResource("/path/to/myresource.rcc"); @@ -62,16 +15,3 @@ MyClass::MyClass() : BaseClass() ... } //! [5] - - -//! [6] -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - Q_INIT_RESOURCE(graphlib); - - QFile file(":/graph.png"); - ... - return app.exec(); -} -//! [6] diff --git a/src/corelib/doc/snippets/code/doc_src_resources.qdoc b/src/corelib/doc/snippets/code/doc_src_resources.qdoc index 9cea681a68..70c2a7b7ab 100644 --- a/src/corelib/doc/snippets/code/doc_src_resources.qdoc +++ b/src/corelib/doc/snippets/code/doc_src_resources.qdoc @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [0] <file alias="cut-img.png">images/cut.png</file> @@ -73,3 +26,7 @@ //! [3] rcc -binary myresource.qrc -o myresource.rcc //! [3] + +//! [4] +<file empty="true">Button.qml</file> +//! [4] diff --git a/src/corelib/doc/snippets/code/qlogging/qlogging.cpp b/src/corelib/doc/snippets/code/qlogging/qlogging.cpp index 8b7104cba5..e61eb70df3 100644 --- a/src/corelib/doc/snippets/code/qlogging/qlogging.cpp +++ b/src/corelib/doc/snippets/code/qlogging/qlogging.cpp @@ -1,61 +1,16 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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_animation_qparallelanimationgroup.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp index 472c5d41c4..6328cb0011 100644 --- a/src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QParallelAnimationGroup *group = new QParallelAnimationGroup; diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp index 7bd8121b90..4b77ab607d 100644 --- a/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp @@ -1,59 +1,95 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] - QPropertyAnimation *animation = new QPropertyAnimation(myWidget, "geometry"); - animation->setDuration(10000); - animation->setStartValue(QRect(0, 0, 100, 30)); - animation->setEndValue(QRect(250, 250, 100, 30)); +#include <QApplication> +#include <QPushButton> +#include <QPropertyAnimation> - animation->start(); +class MyButtonWidget : public QWidget +{ +public: + MyButtonWidget(QWidget *parent = nullptr); +}; + +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *button = new QPushButton(tr("Animated Button"), this); + QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this); + anim->setDuration(10000); + anim->setStartValue(QPoint(0, 0)); + anim->setEndValue(QPoint(100, 250)); + anim->start(); +} + +int main(int argc, char *argv[]) +{ + QApplication a(argc, argv); + MyButtonWidget buttonAnimWidget; + buttonAnimWidget.resize(QSize(800, 600)); + buttonAnimWidget.show(); + return a.exec(); +} //! [0] + + +//! [easing-curve] +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *button = new QPushButton(tr("Animated Button"), this); + QPropertyAnimation *anim = new QPropertyAnimation(button, "pos", this); + anim->setDuration(10000); + anim->setStartValue(QPoint(0, 0)); + anim->setEndValue(QPoint(100, 250)); + anim->setEasingCurve(QEasingCurve::OutBounce); + anim->start(); +} +//! [easing-curve] + + +//! [animation-group1] +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *bonnie = new QPushButton(tr("Bonnie"), this); + QPushButton *clyde = new QPushButton(tr("Clyde"), this); + + QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "pos", this); + anim1->setDuration(3000); + anim1->setStartValue(QPoint(0, 0)); + anim1->setEndValue(QPoint(100, 250)); + + QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "pos", this); + anim2->setDuration(3000); + anim2->setStartValue(QPoint(100, 250)); + anim2->setEndValue(QPoint(500, 500)); + + QParallelAnimationGroup *parallelAnim = new QParallelAnimationGroup; + parallelAnim->addAnimation(anim1); + parallelAnim->addAnimation(anim2); + parallelAnim->start(); +} +//! [animation-group1] + +//! [animation-group2] +MyButtonWidget::MyButtonWidget(QWidget *parent) : QWidget(parent) +{ + QPushButton *bonnie = new QPushButton(tr("Bonnie"), this); + QPushButton *clyde = new QPushButton(tr("Clyde"), this); + + QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "pos", this); + anim1->setDuration(3000); + anim1->setStartValue(QPoint(0, 0)); + anim1->setEndValue(QPoint(100, 250)); + + QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "pos", this); + anim2->setDuration(3000); + anim2->setStartValue(QPoint(0, 0)); + anim2->setEndValue(QPoint(200, 250)); + + QSequentialAnimationGroup *sequenceAnim = new QSequentialAnimationGroup; + sequenceAnim->addAnimation(anim1); + sequenceAnim->addAnimation(anim2); + sequenceAnim->start(); +} +//! [animation-group2] diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp index 0eff184926..a429fe20b2 100644 --- a/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QSequentialAnimationGroup *group = new QSequentialAnimationGroup; diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp index 0808dcc145..be7f549f65 100644 --- a/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QVariant myColorInterpolator(const QColor &start, const QColor &end, qreal progress) diff --git a/src/corelib/doc/snippets/code/src_corelib_concurrent_qthreadpool.cpp b/src/corelib/doc/snippets/code/src_corelib_concurrent_qthreadpool.cpp index 8490942048..4cba70e62d 100644 --- a/src/corelib/doc/snippets/code/src_corelib_concurrent_qthreadpool.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_concurrent_qthreadpool.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] class HelloWorldTask : public QRunnable 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 a540b88247..25d3abf67e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] label->setAlignment(Qt::AlignLeft | Qt::AlignTop); @@ -79,17 +32,6 @@ Q_FLAG(Options) typedef QFlags<Enum> Flags; //! [2] - -//! [3] -int myValue = 10; -int minValue = 2; -int maxValue = 6; - -int boundedValue = qBound(minValue, myValue, maxValue); -// boundedValue == 6 -//! [3] - - //! [4] if (!driver()->isOpen() || driver()->isOpenError()) { qWarning("QSqlQuery::exec: database not open"); @@ -108,11 +50,6 @@ quint64 value = Q_UINT64_C(932838457459459); //! [6] -//! [7] -void myMsgHandler(QtMsgType, const char *); -//! [7] - - //! [8] qint64 value = Q_INT64_C(932838457459459); //! [8] @@ -203,7 +140,7 @@ int boundedValue = qBound(minValue, myValue, maxValue); //! [16] -#if QT_VERSION >= 0x040100 +#if QT_VERSION >= QT_VERSION_CHECK(4, 1, 0) QIcon icon = style()->standardIcon(QStyle::SP_TrashIcon); #else QPixmap pixmap = style()->standardPixmap(QStyle::SP_TrashIcon); @@ -273,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(); @@ -339,8 +265,7 @@ void f(int c) //! [27] -qWarning() << "Brush:" << myQBrush << "Other value:" -<< i; +qWarning() << "Brush:" << myQBrush << "Other value:" << i; //! [27] @@ -355,8 +280,7 @@ void load(const QString &fileName) //! [29] -qCritical() << "Brush:" << myQBrush << "Other -value:" << i; +qCritical() << "Brush:" << myQBrush << "Other value:" << i; //! [29] @@ -514,16 +438,20 @@ void TheClass::addLabels() } //! [qttrid_noop] +//! [qttrid_n_noop] +static const char * const ids[] = { + //% "%n foo(s) found." + QT_TRID_N_NOOP("qtn_foo"), + //% "%n bar(s) found." + QT_TRID_N_NOOP("qtn_bar"), + 0 +}; -//! [37] -qWarning("%s: %s", qUtf8Printable(key), qUtf8Printable(value)); -//! [37] - - -//! [qUtf16Printable] -qWarning("%ls: %ls", qUtf16Printable(key), qUtf16Printable(value)); -//! [qUtf16Printable] - +QString result(int type, int n) +{ + return qtTrId(ids[type], n); +} +//! [qttrid_n_noop] //! [38] struct Point2D @@ -553,7 +481,7 @@ private: int *data; }; -Q_DECLARE_TYPEINFO(Point2D, Q_MOVABLE_TYPE); +Q_DECLARE_TYPEINFO(Point2D, Q_RELOCATABLE_TYPE); //! [39] @@ -624,11 +552,6 @@ qFuzzyCompare(0.0, 1.0e-200); // This will return false qFuzzyCompare(1 + 0.0, 1 + 1.0e-200); // This will return true //! [46] -//! [47] -CApaApplication *myApplicationFactory(); -//! [47] - - //! [49] void myMessageHandler(QtMsgType, const QMessageLogContext &, const QString &); //! [49] @@ -656,11 +579,6 @@ template<> class QTypeInfo<A> : public QTypeInfoMerger<A, B, C, D> {}; ... qOverload<int, const QString &>(&Foo::overloadedFunction) //! [52] -//! [53] - ... QOverload<>::of(&Foo::overloadedFunction) - ... QOverload<int, const QString &>::of(&Foo::overloadedFunction) -//! [53] - //! [54] struct Foo { void overloadedFunction(int, const QString &); @@ -720,7 +638,7 @@ bool readConfiguration(const QFile &file) //! [qt-version-check] #include <QtGlobal> -#if (QT_VERSION >= QT_VERSION_CHECK(5, 0, 0)) +#if QT_VERSION >= QT_VERSION_CHECK(5, 0, 0) #include <QtWidgets> #else #include <QtGui> diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp index 7589050bc2..d04e243b71 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz t} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}" diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp index d281089041..d88675d8f1 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] if (qFloatDistance(a, b) < (1 << 7)) { // The last 7 bits are not diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp index c712dfa432..d86d40bc98 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QOperatingSystemVersion::current() >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 9) diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp index 9f2884667c..8be3f91120 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp @@ -1,53 +1,6 @@ -/**************************************************************************** -** -** Copyright (C) 2018 Intel Corporation. -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 Intel Corporation. +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] quint32 value = QRandomGenerator::global()->generate(); @@ -127,5 +80,5 @@ //! [15] //! [16] - qint64 value = QRandomGenerator64::generate() & std::numeric_limits<qint64>::max(); + qint64 value = QRandomGenerator64::global()->generate() & std::numeric_limits<qint64>::max(); //! [16] 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 ae2f305313..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,64 +1,21 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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) @@ -74,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] @@ -97,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_qdatastream.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdatastream.cpp index efc06d8c62..3075913a95 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qdatastream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdatastream.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause void wrapInFunction() { diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp index 5154dc5d68..5411ab34f6 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QString s; diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdir.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdir.cpp index 4e5e25a64a..400b3225d0 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qdir.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdir.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause void wrapInFunction() @@ -54,7 +7,7 @@ void wrapInFunction() //! [0] QDir("/home/user/Documents") -QDir("C:/Documents and Settings") +QDir("C:/Users") //! [0] @@ -154,7 +107,7 @@ if (d1 != d2) //! [12] -C:/Documents and Settings/Username +C:/Users/Username //! [12] @@ -182,4 +135,17 @@ namespace MyNamespace Q_CLEANUP_RESOURCE(myapp); //! [15] +//! [16] +QString absolute = "/local/bin"; +QString relative = "local/bin"; +QFileInfo absFile(absolute); +QFileInfo relFile(relative); + +QDir::setCurrent(QDir::rootPath()); +// absFile and relFile now point to the same file + +QDir::setCurrent("/tmp"); +// absFile now points to "/local/bin", +// while relFile points to "/tmp/local/bin" +//! [16] } diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdiriterator.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdiriterator.cpp index 31442a5516..ec3f3adc50 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qdiriterator.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdiriterator.cpp @@ -1,58 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QDirIterator it("/etc", QDirIterator::Subdirectories); while (it.hasNext()) { - qDebug() << it.next(); - + QString dir = it.next(); + qDebug() << dir; // /etc/. // /etc/.. // /etc/X11 @@ -69,3 +22,7 @@ while (it.hasNext()) { qDebug() << f.fileName() << f.readAll().trimmed().toDouble() / 1000 << "MHz"; } //! [1] + +//! [2] +QDirIterator audioFileIt(audioPath, {"*.mp3", "*.wav"}, QDir::Files); +//! [2] 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_qfile.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qfile.cpp index 4123fe4996..3a8f7d2747 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qfile.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qfile.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QFile file; @@ -57,16 +10,6 @@ file.open(QIODevice::ReadOnly); // opens "/home/readme.txt" under Unix //! [0] -//! [1] -QByteArray myEncoderFunc(const QString &fileName); -//! [1] - - -//! [2] -QString myDecoderFunc(const QByteArray &localFileName); -//! [2] - - //! [3] #include <stdio.h> 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 036625370e..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,58 +1,21 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 @@ -69,15 +32,15 @@ info2.size(); // returns 56201 #endif //! [0] - +} //! [1] #ifdef Q_OS_WIN -QFileInfo info1("C:\\Documents and Settings\\Bob\\untabify.lnk"); +QFileInfo info1("C:\\Users\\Bob\\untabify.lnk"); info1.isSymLink(); // returns true -info1.absoluteFilePath(); // returns "C:/Documents and Settings/Bob/untabify.lnk" -info1.size(); // returns 743 +info1.absoluteFilePath(); // returns "C:/Users/Bob/untabify.lnk" +info1.size(); // returns 63942 info1.symLinkTarget(); // returns "C:/Pretty++/untabify" QFileInfo info2(info1.symLinkTarget()); @@ -88,65 +51,72 @@ info2.size(); // returns 63942 #endif //! [1] - +{ //! [2] -QString absolute = "/local/bin"; -QString relative = "local/bin"; -QFileInfo absFile(absolute); -QFileInfo relFile(relative); +QFileInfo info("/usr/bin/env"); -QDir::setCurrent(QDir::rootPath()); -// absFile and relFile now point to the same file +QString path = info.absolutePath(); // path = /usr/bin +QString base = info.baseName(); // base = env -QDir::setCurrent("/tmp"); -// absFile now points to "/local/bin", -// while relFile points to "/tmp/local/bin" -//! [2] +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)) @@ -154,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_qfileselector.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp index 0d1aa691cf..facf037f46 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QString defaultsBasePath = "data/"; diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qiodevice.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qiodevice.cpp index 981f6b3f12..dc58d722c3 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qiodevice.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qiodevice.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QProcess gzip; diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp index cab48f1e27..0a7a718e31 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] <category>[.<type>] = true|false diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp index 8a2825cd10..765c1e41cf 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause void wrapInFunction() @@ -90,34 +43,28 @@ process2.start("command2"); //! [4] -class SandboxProcess : public QProcess +void runSandboxed(const QString &name, const QStringList &arguments) { - ... - protected: - void setupChildProcess() override; - ... -}; - -void SandboxProcess::setupChildProcess() -{ - // Drop all privileges in the child process, and enter - // a chroot jail. -#if defined Q_OS_UNIX - ::setgroups(0, 0); - ::chroot("/etc/safe"); - ::chdir("/"); - ::setgid(safeGid); - ::setuid(safeUid); - ::umask(0); -#endif + QProcess proc; + proc.setChildProcessModifier([] { + // Drop all privileges in the child process, and enter + // a chroot jail. + ::setgroups(0, nullptr); + ::chroot("/run/safedir"); + ::chdir("/"); + ::setgid(safeGid); + ::setuid(safeUid); + ::umask(077); + }); + proc.start(name, arguments); + proc.waitForFinished(); } - //! [4] //! [5] QProcess process; -process.start("del /s *.txt"); +process.startCommand("del /s *.txt"); // same as process.start("del", QStringList() << "/s" << "*.txt"); ... //! [5] @@ -125,13 +72,13 @@ process.start("del /s *.txt"); //! [6] QProcess process; -process.start("dir \"My Documents\""); +process.startCommand("dir \"My Documents\""); //! [6] //! [7] QProcess process; -process.start("dir \"Epic 12\"\"\" Singles\""); +process.startCommand("dir \"Epic 12\"\"\" Singles\""); //! [7] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp index 08ab1fb338..5774add2a7 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qsettings.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QSettings settings("MySoft", "Star Runner"); @@ -92,7 +45,7 @@ settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default"); // re //! [7] -#ifdef Q_OS_MAC +#ifdef Q_OS_DARWIN QSettings settings("grenoullelogique.fr", "Squash"); #else QSettings settings("Grenoulle Logique", "Squash"); @@ -185,10 +138,10 @@ QList<Login> logins; QSettings settings; settings.beginWriteArray("logins"); -for (int i = 0; i < logins.size(); ++i) { +for (qsizetype i = 0; i < logins.size(); ++i) { settings.setArrayIndex(i); - settings.setValue("userName", list.at(i).userName); - settings.setValue("password", list.at(i).password); + settings.setValue("userName", logins.at(i).userName); + settings.setValue("password", logins.at(i).password); } settings.endArray(); //! [16] 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 c7a1b34f7a..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,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2014 Ivan Komissarov -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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()); diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qtemporarydir.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qtemporarydir.cpp index 0fab8566e5..037cf8a36d 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qtemporarydir.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qtemporarydir.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause { //! [0] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp index 4e864b3dcd..76adfd3128 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause { //! [0] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qtextstream.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qtextstream.cpp index 4795650748..75a04e654f 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qtextstream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qtextstream.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QFile data("output.txt"); @@ -131,9 +84,3 @@ out << "Qt rocks!" << Qt::endl; //! [9] stream << '\n' << Qt::flush; //! [9] - - -//! [10] -QTextStream out(&file); -out.setEncoding(QStringConverter::Utf8); -//! [10] 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 e3c3005c33..945f3ae3e7 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp @@ -1,52 +1,13 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [constructor-url-reference] +QUrl url("example.com"); +//! [constructor-url-reference] + +//! [constructor-url] +QUrl url("https://example.com"); +//! [constructor-url] //! [0] QUrl url("http://www.example.com/List of holidays.xml"); @@ -78,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_io_qurlquery.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp index 22f1d3260f..c2085fddc3 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] sub-delims = "!" / "$" / "&" / "'" / "(" / ")" diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp index 2e055ec439..4fd7f97ae8 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] beginInsertRows(parent, 2, 4); @@ -97,16 +50,6 @@ beginMoveRows(parent, 2, 2, parent, 0); beginMoveRows(parent, 2, 2, parent, 4); //! [9] -//! [10] -myData.clear(); -reset(); -//! [10] - -//! [11] -beginResetModel(); -myData.clear(); -endResetModel(); -//! [11] //! [12] class CustomDataProxy : public QSortFilterProxyModel @@ -141,3 +84,48 @@ private: }; //! [12] +//! [13] +QVariant text = model->data(index, Qt::DisplayRole); +QVariant decoration = model->data(index, Qt::DecorationRole); +QVariant checkState = model->data(index, Qt::CheckStateRole); +// etc. +//! [13] + +//! [14] +std::array<QModelRoleData, 3> roleData = { { + QModelRoleData(Qt::DisplayRole), + QModelRoleData(Qt::DecorationRole), + QModelRoleData(Qt::CheckStateRole) +} }; + +// Usually, this is not necessary: A QModelRoleDataSpan +// will be built automatically for you when passing an array-like +// container to multiData(). +QModelRoleDataSpan span(roleData); + +model->multiData(index, span); + +// Use roleData[0].data(), roleData[1].data(), etc. +//! [14] + +//! [15] +void MyModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const +{ + for (QModelRoleData &roleData : roleDataSpan) { + int role = roleData.role(); + + // ... obtain the data for index and role ... + + roleData.setData(result); + } +} +//! [15] + +//! [16] +QVariant MyModel::data(const QModelIndex &index, int role) const +{ + QModelRoleData roleData(role); + multiData(index, roleData); + return roleData.data(); +} +//! [16] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.cpp index b84cf0ae2d..62844e08cb 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.cpp @@ -1,58 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] class MyXcbEventFilter : public QAbstractNativeEventFilter { public: - bool nativeEventFilter(const QByteArray &eventType, void *message, long *) override + bool nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) override { if (eventType == "xcb_generic_event_t") { xcb_generic_event_t* ev = static_cast<xcb_generic_event_t *>(message); diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h index bb44782ac5..905a79b105 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Samuel Gaist <samuel.gaist@edeltech.ch> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Samuel Gaist <samuel.gaist@edeltech.ch> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] #include <QAbstractNativeEventFilter> @@ -54,6 +7,6 @@ class MyCocoaEventFilter : public QAbstractNativeEventFilter { public: - bool nativeEventFilter(const QByteArray &eventType, void *message, long *) override; + bool nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) override; }; //! [0] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm index 7c40330de0..fb6d602eaf 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter.mm @@ -1,59 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Samuel Gaist <samuel.gaist@edeltech.ch> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Samuel Gaist <samuel.gaist@edeltech.ch> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] #include "mycocoaeventfilter.h" #import <AppKit/AppKit.h> -bool CocoaNativeEventFilter::nativeEventFilter(const QByteArray &eventType, void *message, long *) +bool MyCocoaEventFilter::nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) { if (eventType == "mac_generic_NSEvent") { NSEvent *event = static_cast<NSEvent *>(message); diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter_win.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter_win.cpp new file mode 100644 index 0000000000..de03f7b6d4 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qabstractnativeeventfilter_win.cpp @@ -0,0 +1,20 @@ +// Copyright (C) 2022 Laszlo Papp <lpapp@kde.org> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [0] +class MyMSGEventFilter : public QAbstractNativeEventFilter +{ +public: + bool nativeEventFilter(const QByteArray &eventType, void *message, qintptr *) override + { + if (eventType == "windows_generic_MSG") { + MSG *msg = static_cast<MSG *>(message); + // ... + } else if (eventType == "windows_dispatcher_MSG") { + MSG *msg = static_cast<MSG *>(message); + // ... + } + return false; + } +}; +//! [0] 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 36b47e6f6e..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,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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); @@ -60,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() @@ -126,8 +75,6 @@ private: //! [6] static inline QString tr(const char *sourceText, const char *comment = nullptr); -static inline QString trUtf8(const char *sourceText, - const char *comment = nullptr); //! [6] 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 35c06f842e..f7440f2bb0 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp @@ -1,59 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void executeOperation(int msecs) { QDeadlineTimer deadline(msecs); do { - if (readFromDevice(deadline.remainingTime()) + if (readFromDevice(deadline.remainingTime())) break; waitForReadyRead(deadline); } while (!deadline.hasExpired()); @@ -110,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_qmath.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmath.cpp index 329f7a494a..7d1d3bd98d 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmath.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmath.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Laszlo Papp <lpapp@kde.org> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Laszlo Papp <lpapp@kde.org> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] float degrees = 180.0f diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp index 56d1fa5a63..ec4646c520 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause void wrapInFunction() @@ -81,6 +34,21 @@ QMetaObject::invokeMethod(thread, "quit", QMetaObject::invokeMethod: Unable to handle unregistered datatype 'MyType' //! [3] +//! [invokemethod-no-macro] +QString retVal; +QMetaObject::invokeMethod(obj, "compute", Qt::DirectConnection, + qReturnArg(retVal), + QString("sqrt"), 42, 9.7); +//! [invokemethod-no-macro] + + +//! [invokemethod-no-macro-other-types] +QString retVal; +QMetaObject::invokeMethod(obj, "compute", Qt::DirectConnection, + qReturnArg(retVal), + QStringView("sqrt"), qsizetype(42), 9.7f); +//! [invokemethod-no-macro-other-types] + //! [4] QString retVal; @@ -130,6 +98,24 @@ method.invoke(pushButton, Qt::QueuedConnection); QMetaMethod::invoke: Unable to handle unregistered datatype 'MyType' //! [7] +//! [invoke-no-macro] +QString retVal; +QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QString, int, double)"); +int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature); +QMetaMethod method = obj->metaObject()->method(methodIndex); +method.invoke(obj, Qt::DirectConnection, qReturnArg(retVal), + QString("sqrt"), 42, 9.7); +//! [invoke-no-macro] + +//! [invoke-no-macro-other-types] +QString retVal; +QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QByteArray, qint64, long double)"); +int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature); +QMetaMethod method = obj->metaObject()->method(methodIndex); +method.invoke(obj, Qt::DirectConnection, qReturnArg(retVal), + QByteArray("sqrt"), qint64(42), 9.7L); +//! [invoke-no-macro-other-types] + //! [8] QString retVal; QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QString, int, double)"); diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp index d28a0ac956..757700786e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetatype.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] struct MyStruct @@ -82,12 +35,12 @@ MyStruct s2 = var.value<MyStruct>(); //! [3] -int id = QMetaType::type("MyClass"); -if (id != QMetaType::UnknownType) { - void *myClassPtr = QMetaType::create(id); +QMetaType type = QMetaType::fromName("MyClass"); +if (type.isValid()) { + void *myClassPtr = type.create(); ... - QMetaType::destroy(id, myClassPtr); - myClassPtr = 0; + type.destroy(myClassPtr); + myClassPtr = nullptr; } //! [3] @@ -97,11 +50,6 @@ qRegisterMetaType<MyClass>("MyClass"); //! [4] -//! [5] -qRegisterMetaTypeStreamOperators<MyClass>("MyClass"); -//! [5] - - //! [6] QDataStream &operator<<(QDataStream &out, const MyClass &myObj); QDataStream &operator>>(QDataStream &in, MyClass &myObj); @@ -153,16 +101,6 @@ void someFunc() //! [11] -//! [12] -QPointer<QFile> fp(new QFile); -QVariant var = QVariant::fromValue(fp); -// ... -if (var.canConvert<QObject*>()) { - QObject *sp = var.value<QObject*>(); - qDebug() << sp->metaObject()->className(); // Prints 'QFile'. -} -//! [12] - //! [13] #include <memory> 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 a87c67dfed..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,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 fddda64b19..e3bbac7a3c 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [1] QObject *obj = new QPushButton; @@ -176,13 +129,6 @@ void MyObject::timerEvent(QTimerEvent *event) //! [8] -//! [9] -QList<QObject *> list = window()->queryList("QAbstractButton")); -foreach (QObject *obj, list) - static_cast<QAbstractButton *>(obj)->setEnabled(false); -//! [9] - - //! [10] QPushButton *button = parentWidget->findChild<QPushButton *>("button1"); //! [10] @@ -251,22 +197,6 @@ MyWindow::MyWindow() } -//! [18] -int n = messages.count(); -showMessage(tr("%n message(s) saved", "", n)); -//! [18] - - -//! [19] -n == 1 ? tr("%n message saved") : tr("%n messages saved") -//! [19] - - -//! [20] -label->setText(tr("F\374r \310lise")); -//! [20] - - //! [21] if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) { QByteArray data; @@ -430,26 +360,18 @@ public: //! [39] -//! [40] -//: This name refers to a host name. -hostNameLabel->setText(tr("Name:")); - -/*: This text refers to a C++ code example. */ -QString example = tr("Example"); -//! [40] - //! [41] QPushButton *button = parentWidget->findChild<QPushButton *>("button1", Qt::FindDirectChildrenOnly); //! [41] //! [42] -QListWidget *list = parentWidget->findChild<QListWidget *>(QString(), Qt::FindDirectChildrenOnly); +QListWidget *list = parentWidget->findChild<QListWidget *>(Qt::FindDirectChildrenOnly); //! [42] //! [43] -QList<QPushButton *> childButtons = parentWidget.findChildren<QPushButton *>(QString(), Qt::FindDirectChildrenOnly); +QList<QPushButton *> childButtons = parentWidget.findChildren<QPushButton *>(Qt::FindDirectChildrenOnly); //! [43] //! [44] @@ -534,18 +456,6 @@ public: }; //! [52] -//! [meta data] -//: This is a comment for the translator. -//= qtn_foo_bar -//~ loc-layout_id foo_dialog -//~ loc-blank False -//~ magic-stuff This might mean something magic. -QString text = MyMagicClass::tr("Sim sala bim."); -//! [meta data] - -//! [explicit tr context] -QString text = QScrollBar::tr("Page up"); -//! [explicit tr context] //! [53] { @@ -559,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_qproperty.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qproperty.cpp new file mode 100644 index 0000000000..c2b55c9684 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qproperty.cpp @@ -0,0 +1,152 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QObject> +#include <QDebug> + +//! [0] +class MyClass : public QObject +{ + Q_OBJECT + Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX) +public: + int x() const { return xProp; } + void setX(int x) { xProp = x; } + QBindable<int> bindableX() { return QBindable<int>(&xProp); } + +signals: + void xChanged(); + +private: + // Declare the instance of the bindable property data. + Q_OBJECT_BINDABLE_PROPERTY(MyClass, int, xProp, &MyClass::xChanged) +}; +//! [0] + +//! [1] +class MyClass : public QObject +{ + Q_OBJECT + Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX) +public: + int x() const { return xProp; } + void setX(int x) { xProp = x; } + QBindable<int> bindableX() { return QBindable<int>(&xProp); } + +signals: + void xChanged(); + +private: + // Declare the instance of int bindable property data and + // initialize it with the value 5. + // This is similar to declaring + // int xProp = 5; + // without using the new QObjectBindableProperty class. + Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(MyClass, int, xProp, 5, &MyClass::xChanged) +}; +//! [1] + +//! [2] +class CustomType +{ +public: + CustomType(int val, int otherVal) : value(val), anotherValue(otherVal) { } + +private: + int value = 0; + int anotherValue = 0; +}; + +// later when using CustomType as a property +Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(MyClass, CustomType xProp, CustomType(5, 10), + &MyClass::xChanged) +//! [2] + +void usage_QBindable() { + //! [3] + MyClass *myObject; + QBindable<int> bindableX = myObject->bindableX(); + qDebug() << bindableX.hasBinding(); // prints false + QProperty<int> y {42}; + bindableX.setBinding([&](){ return 2*y.value(); }); + qDebug() << bindableX.hasBinding() << myObject->x(); // prints true 84 + //! [3] +} + +//! [4] +#include <QObject> +#include <QProperty> +#include <QDebug> + +class Foo : public QObject +{ + Q_OBJECT + Q_PROPERTY(int myVal READ myVal WRITE setMyVal BINDABLE bindableMyVal) +public: + int myVal() { return myValMember.value(); } + void setMyVal(int newvalue) { myValMember = newvalue; } + QBindable<int> bindableMyVal() { return &myValMember; } +signals: + void myValChanged(); + +private: + Q_OBJECT_BINDABLE_PROPERTY(Foo, int, myValMember, &Foo::myValChanged); +}; + +int main() +{ + bool debugout(true); // enable debug log + Foo myfoo; + QProperty<int> prop(42); + QObject::connect(&myfoo, &Foo::myValChanged, [&]() { + if (debugout) + qDebug() << myfoo.myVal(); + }); + myfoo.bindableMyVal().setBinding([&]() { return prop.value(); }); // prints "42" + + prop = 5; // prints "5" + debugout = false; + prop = 6; // prints nothing + debugout = true; + prop = 7; // prints "7" +} + +#include "main.moc" +//! [4] + +//! [5] +class Client{}; + +class MyClassPrivate : public QObjectPrivate +{ +public: + QList<Client> clients; + bool hasClientsActualCalculation() const { return clients.size() > 0; } + Q_OBJECT_COMPUTED_PROPERTY(MyClassPrivate, bool, hasClientsData, + &MyClassPrivate::hasClientsActualCalculation) +}; + +class MyClass : public QObject +{ + Q_OBJECT + Q_PROPERTY(bool hasClients READ hasClients STORED false BINDABLE bindableHasClients) +public: + QBindable<bool> bindableHasClients() + { + return QBindable<bool>(&d_func()->hasClientsData); + } + bool hasClients() const + { + return d_func()->hasClientsData.value(); + } + void addClient(const Client &c) + { + Q_D(MyClass); + d->clients.push_back(c); + // notify that the value could have changed + d->hasClientsData.notify(); + } +private: + Q_DECLARE_PRIVATE(MyClass) +}; +//! [5] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp index 345a59b7ec..45da88c75d 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp @@ -1,55 +1,8 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] -QSystemSemaphore sem("market", 3, QSystemSemaphore::Create); +QSystemSemaphore sem(QSystemSemaphore::platformSafeKey("market"), 3, QSystemSemaphore::Create); // resources available == 3 sem.acquire(); // resources available == 2 sem.acquire(); // resources available == 1 @@ -60,7 +13,7 @@ sem.release(2); // resources available == 3 //! [1] -QSystemSemaphore sem("market", 5, QSystemSemaphore::Create); +QSystemSemaphore sem(QSystemSemaphore::platformSafeKey("market"), 5, QSystemSemaphore::Create); for (int i = 0; i < 5; ++i) // acquire all 5 resources sem.acquire(); sem.release(5); // release the 5 resources diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp index 548e32dc5d..5edcaae755 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qtimer.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] #include <QApplication> @@ -55,7 +8,7 @@ int main(int argc, char *argv[]) { QApplication app(argc, argv); - QTimer::singleShot(600000, &app, SLOT(quit())); + QTimer::singleShot(600000, &app, QCoreApplication::quit); ... return app.exec(); } diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qvariant.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qvariant.cpp index ca1ea21b02..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,59 +1,13 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 int x = v.toInt(); // x = 123 out << v; // Writes a type tag and an int to out -v = QVariant("hello"); // The variant now contains a QByteArray v = QVariant(tr("hello")); // The variant now contains a QString int y = v.toInt(); // y = 0 since v cannot be converted to an int QString s = v.toString(); // s = tr("hello") (see QObject::tr()) @@ -64,16 +18,13 @@ in >> v; // Reads an Int variant int z = v.toInt(); // z = 123 qDebug("Type is %s", // prints "Type is int" v.typeName()); -v = v.toInt() + 100; // The variant now hold the value 223 -v = QVariant(QStringList()); +v = v.toInt() + 100; // The variant now holds the value 223 +v = QVariant(QStringList()); // The variant now holds a QStringList //! [0] - //! [1] -QVariant x, y(QString()), z(QString("")); -x.convert(QVariant::Int); -// x.isNull() == true -// y.isNull() == true, z.isNull() == false +QVariant x; // x.isNull() == true +QVariant y = QVariant::fromValue(nullptr); // y.isNull() == true //! [1] @@ -95,7 +46,7 @@ QVariant v; v.setValue(5); int i = v.toInt(); // i is now 5 -QString s = v.toString() // s is now "5" +QString s = v.toString(); // s is now "5" MyCustomStruct c; v.setValue(c); @@ -140,11 +91,6 @@ return QVariant::fromValue(s); //! [7] -//! [8] -QObject *object = getObjectFromSomewhere(); -QVariant data = QVariant::fromValue(object); -//! [8] - //! [9] QList<int> intList = {7, 11, 42}; diff --git a/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp b/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp index 3092e32f6f..7ed52617e7 100644 --- a/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp @@ -1,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +using namespace Qt::StringLiterals; //! [0] QMimeDatabase db; @@ -57,7 +12,7 @@ if (mime.inherits("text/plain")) { //! [0] //! [1] -QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QLatin1String("mime/packages"), +QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, "mime/packages"_L1, QStandardPaths::LocateDirectory); //! [1] diff --git a/src/corelib/doc/snippets/code/src_corelib_plugin_qlibrary.cpp b/src/corelib/doc/snippets/code/src_corelib_plugin_qlibrary.cpp index 6abd2f6d2b..6edb937208 100644 --- a/src/corelib/doc/snippets/code/src_corelib_plugin_qlibrary.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_plugin_qlibrary.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QLibrary myLib("mylib"); diff --git a/src/corelib/doc/snippets/code/src_corelib_plugin_quuid.cpp b/src/corelib/doc/snippets/code/src_corelib_plugin_quuid.cpp index 2ba231d1cc..4d8f0b8d34 100644 --- a/src/corelib/doc/snippets/code/src_corelib_plugin_quuid.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_plugin_quuid.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] // {67C8770B-44F1-410A-AB9A-F9B5446F13EE} 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 cb6928b129..acb5a6272e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp @@ -1,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +using namespace Qt::StringLiterals; //! [0] QCborValue(QCborTag(2), QByteArray("\x01\0\0\0\0\0\0\0\0", 9)); @@ -55,18 +10,18 @@ //! [1] writer.startMap(4); // 4 elements in the map - writer.append(QLatin1String("label")); - writer.append(QLatin1String("journald")); + writer.append("label"_L1); + writer.append("journald"_L1); - writer.append(QLatin1String("autoDetect")); + writer.append("autoDetect"_L1); writer.append(false); - writer.append(QLatin1String("condition")); - writer.append(QLatin1String("libs.journald")); + writer.append("condition"_L1); + writer.append("libs.journald"_L1); - writer.append(QLatin1String("output")); + writer.append("output"_L1); writer.startArray(1); - writer.append(QLatin1String("privateFeature")); + writer.append("privateFeature"_L1); writer.endArray(); writer.endMap(); @@ -118,7 +73,7 @@ //! [7] //! [8] - writer.append(QLatin1String("Hello, World")); + writer.append("Hello, World"_L1); //! [8] //! [9] @@ -228,7 +183,7 @@ //! [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) { @@ -243,7 +198,7 @@ void appendMap(QCborStreamWriter &writer, const QMap<int, QString> &map) { writer.startMap(map.size()); - for (auto it = map.begin(); it != map.end(); ++it) { + for (auto it = map.cbegin(), end = map.cend(); it != end; ++it) { writer.append(it.key()); writer.append(it.value()); } @@ -316,12 +271,12 @@ { 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(); } @@ -334,12 +289,12 @@ { 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_qcborvalue.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp index 5406536cfe..3abee048ab 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QCborValue(uuid) == QCborValue(QCborKnownTags::Uuid, uuid.toRfc4122()); 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 cfcc2f8f94..dfdebe6a76 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp @@ -1,59 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// 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_serialization_qjsondocument.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp index 1fe328c0a0..0cb11ed872 100644 --- a/src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] { diff --git a/src/corelib/doc/snippets/code/src_corelib_statemachine_qstatemachine.cpp b/src/corelib/doc/snippets/code/src_corelib_statemachine_qstatemachine.cpp deleted file mode 100644 index c756116de4..0000000000 --- a/src/corelib/doc/snippets/code/src_corelib_statemachine_qstatemachine.cpp +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [simple state machine] -QPushButton button; - -QStateMachine machine; -QState *s1 = new QState(); -s1->assignProperty(&button, "text", "Click me"); - -QFinalState *s2 = new QFinalState(); -s1->addTransition(&button, &QPushButton::clicked, s2); - -machine.addState(s1); -machine.addState(s2); -machine.setInitialState(s1); -machine.start(); -//! [simple state machine] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qanystringview.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qanystringview.cpp new file mode 100644 index 0000000000..370c6fd3e0 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_text_qanystringview.cpp @@ -0,0 +1,12 @@ +// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [0] + void myfun1(QAnyStringView sv); // preferred + void myfun2(const QAnyStringView &sv); // compiles and works, but slower +//! [0] + +//! [2] + auto sv1 = QAnyStringView{std::begin(array), std::end(array) - 1}; // using C++11 std::begin()/std::end() + auto sv2 = QAnyStringView(array, std::size(array) - 1); // using C++17 std::size() +//! [2] 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 74f14f2a4b..a4fecc41f9 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause void wrapInFunction() @@ -69,9 +22,9 @@ ba[4] = 0xca; //! [2] -for (int i = 0; i < ba.size(); ++i) { +for (qsizetype i = 0; i < ba.size(); ++i) { if (ba.at(i) >= 'a' && ba.at(i) <= 'f') - cout << "Found character in range [a-f]" << Qt::endl; + cout << "Found character in range [a-f]" << endl; } //! [2] @@ -86,9 +39,9 @@ x.replace(5, 3, "&"); // x == "rock & roll" //! [4] QByteArray ba("We must be <b>bold</b>, very <b>bold</b>"); -int j = 0; +qsizetype j = 0; while ((j = ba.indexOf("<b>", j)) != -1) { - cout << "Found <b> tag at index position " << j << Qt::endl; + cout << "Found <b> tag at index position " << j << endl; ++j; } //! [4] @@ -108,7 +61,7 @@ QByteArray("abc").isEmpty(); // returns false //! [6] QByteArray ba("Hello"); -int n = ba.size(); // n == 5 +qsizetype n = ba.size(); // n == 5 ba.data()[0]; // returns 'H' ba.data()[4]; // returns 'o' ba.data()[5]; // returns '\0' @@ -126,7 +79,7 @@ QByteArray("abc").isEmpty(); // returns false QByteArray ba("Hello world"); char *data = ba.data(); while (*data) { - cout << "[" << *data << "]" << Qt::endl; + cout << "[" << *data << "]" << endl; ++data; } //! [8] @@ -195,7 +148,7 @@ x.append(y); //! [17] QByteArray ba("Meal"); -ba.insert(1, QByteArray("ontr")); +ba.insert(1, QByteArrayView("ontr")); // ba == "Montreal" //! [17] @@ -276,22 +229,22 @@ if (url.endsWith(".html")) //! [27] QByteArray x("Pineapple"); -QByteArray y = x.left(4); +QByteArray y = x.first(4); // y == "Pine" //! [27] //! [28] QByteArray x("Pineapple"); -QByteArray y = x.right(5); +QByteArray y = x.last(5); // y == "apple" //! [28] //! [29] QByteArray x("Five pineapples"); -QByteArray y = x.mid(5, 4); // y == "pine" -QByteArray z = x.mid(5); // z == "pineapples" +QByteArray y = x.sliced(5, 4); // y == "pine" +QByteArray z = x.sliced(5); // z == "pineapples" //! [29] @@ -422,7 +375,7 @@ text.data(); // returns "Qt is great!" QByteArray::fromBase64("PHA+SGVsbG8/PC9wPg==", QByteArray::Base64Encoding); // returns "<p>Hello?</p>" QByteArray::fromBase64("PHA-SGVsbG8_PC9wPg==", QByteArray::Base64UrlEncoding); // returns "<p>Hello?</p>" -//! [44bis] +//! [44] //! [44ter] void process(const QByteArray &); @@ -490,13 +443,13 @@ macAddress.toHex(0); // returns "123456abcdef" //! [51] QByteArray text = QByteArray::fromPercentEncoding("Qt%20is%20great%33"); -text.data(); // returns "Qt is great!" +qDebug("%s", text.data()); // reports "Qt is great!" //! [51] //! [52] QByteArray text = "{a fishy string?}"; QByteArray ba = text.toPercentEncoding("{}", "s"); -qDebug(ba.constData()); +qDebug("%s", ba.constData()); // prints "{a fi%73hy %73tring%3F}" //! [52] @@ -504,6 +457,25 @@ qDebug(ba.constData()); QByteArray ba = QByteArrayLiteral("byte array contents"); //! [53] -} +//! [54] +QByteArray encoded("Qt%20is%20great%33"); +QByteArray decoded = encoded.percentDecoded(); // Set to "Qt is great!" +//! [54] +//! [55] +emscripten::val uint8array = emscripten::val::global("g_uint8array"); +QByteArray byteArray = QByteArray::fromEcmaUint8Array(uint8array); +//! [55] +//! [56] +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_qbytearraymatcher.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qbytearraymatcher.cpp index 9cf94f0494..3d750c44ff 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qbytearraymatcher.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qbytearraymatcher.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] static const auto matcher = qMakeStaticByteArrayMatcher("needle"); diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qbytearrayview.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qbytearrayview.cpp index 31a2107c62..4457a71ae5 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qbytearrayview.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qbytearrayview.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore/qbytearrayview.h> //! [0] @@ -59,9 +12,23 @@ void fun(char ch) { fun(QByteArrayView(&ch, 1)); } //! [1] -void wrapper() { - const char array[1] = { 0 }; //! [2] - auto bv = QByteArrayView(array, std::size(array)); // using C++17 std::size() +QByteArrayView str("FF"); +bool ok; +int hex = str.toInt(&ok, 16); // hex == 255, ok == true +int dec = str.toInt(&ok, 10); // dec == 0, ok == false //! [2] -} + +//! [3] +QByteArrayView str("FF"); +bool ok; +long hex = str.toLong(&ok, 16); // hex == 255, ok == true +long dec = str.toLong(&ok, 10); // dec == 0, ok == false +//! [3] + +//! [4] +QByteArrayView string("1234.56 Volt"); +bool ok; +float a = str.toFloat(&ok); // a == 0, ok == false +a = string.first(7).toFloat(&ok); // a == 1234.56, ok == true +//! [4] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qcollator.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qcollator.cpp new file mode 100644 index 0000000000..91da052bf7 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_text_qcollator.cpp @@ -0,0 +1,11 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [0] +QStringList sortedStrings(QStringList seq) +{ + QCollator order; + std::sort(seq.begin(), seq.end(), order); + return seq; +} +//! [0] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qlocale.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qlocale.cpp index aed14c379f..c3c41b250b 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qlocale.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qlocale.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QLocale egyptian(QLocale::Arabic, QLocale::Egypt); @@ -59,24 +12,22 @@ int i = egyptian.toInt(s2); //! [1] -QLocale::setDefault(QLocale(QLocale::Hebrew, QLocale::Israel)); -QLocale hebrew; // Constructs a default QLocale -QString s1 = hebrew.toString(15714.3, 'e'); - bool ok; double d; -QLocale::setDefault(QLocale::C); -d = QString("1234,56").toDouble(&ok); // ok == false -d = QString("1234.56").toDouble(&ok); // ok == true, d == 1234.56 +QLocale::setDefault(QLocale::C); // uses '.' as a decimal point +QLocale cLocale; // default-constructed C locale +d = cLocale.toDouble("1234,56", &ok); // ok == false, d == 0 +d = cLocale.toDouble("1234.56", &ok); // ok == true, d == 1234.56 -QLocale::setDefault(QLocale::German); -d = QString("1234,56").toDouble(&ok); // ok == true, d == 1234.56 -d = QString("1234.56").toDouble(&ok); // ok == true, d == 1234.56 +QLocale::setDefault(QLocale::German); // uses ',' as a decimal point +QLocale german; // default-constructed German locale +d = german.toDouble("1234,56", &ok); // ok == true, d == 1234.56 +d = german.toDouble("1234.56", &ok); // ok == false, d == 0 -QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates)); -str = QString("%1 %L2 %L3") - .arg(12345).arg(12345).arg(12345, 0, 16); +QLocale::setDefault(QLocale::English); +// Default locale now uses ',' as a group separator. +QString str = QString("%1 %L2 %L3").arg(12345).arg(12345).arg(12345, 0, 16); // str == "12345 12,345 3039" //! [1] @@ -92,16 +43,16 @@ bool ok; double d; QLocale c(QLocale::C); -d = c.toDouble( "1234.56", &ok ); // ok == true, d == 1234.56 -d = c.toDouble( "1,234.56", &ok ); // ok == true, d == 1234.56 -d = c.toDouble( "1234,56", &ok ); // ok == false +d = c.toDouble("1234.56", &ok); // ok == true, d == 1234.56 +d = c.toDouble("1,234.56", &ok); // ok == true, d == 1234.56 +d = c.toDouble("1234,56", &ok); // ok == false, d == 0 QLocale german(QLocale::German); -d = german.toDouble( "1234,56", &ok ); // ok == true, d == 1234.56 -d = german.toDouble( "1.234,56", &ok ); // ok == true, d == 1234.56 -d = german.toDouble( "1234.56", &ok ); // ok == false +d = german.toDouble("1234,56", &ok); // ok == true, d == 1234.56 +d = german.toDouble("1.234,56", &ok); // ok == true, d == 1234.56 +d = german.toDouble("1234.56", &ok); // ok == false, d == 0 -d = german.toDouble( "1.234", &ok ); // ok == true, d == 1234.0 +d = german.toDouble("1.234", &ok); // ok == true, d == 1234.0 //! [3] //! [3-qstringview] @@ -109,14 +60,14 @@ bool ok; double d; QLocale c(QLocale::C); -d = c.toDouble(u"1234.56", &ok); // ok == true, d == 1234.56 -d = c.toDouble(u"1,234.56", &ok); // ok == true, d == 1234.56 -d = c.toDouble(u"1234,56", &ok); // ok == false +d = c.toDouble(u"1234.56", &ok); // ok == true, d == 1234.56 +d = c.toDouble(u"1,234.56", &ok); // ok == true, d == 1234.56 +d = c.toDouble(u"1234,56", &ok); // ok == false, d == 0 QLocale german(QLocale::German); -d = german.toDouble(u"1234,56", &ok); // ok == true, d == 1234.56 -d = german.toDouble(u"1.234,56", &ok); // ok == true, d == 1234.56 -d = german.toDouble(u"1234.56", &ok); // ok == false +d = german.toDouble(u"1234,56", &ok); // ok == true, d == 1234.56 +d = german.toDouble(u"1.234,56", &ok); // ok == true, d == 1234.56 +d = german.toDouble(u"1234.56", &ok); // ok == false, d == 0 -d = german.toDouble(u"1.234", &ok); // ok == true, d == 1234.0 +d = german.toDouble(u"1.234", &ok); // ok == true, d == 1234.0 //! [3-qstringview] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qregularexpression.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qregularexpression.cpp index b451ed5253..03fdda9987 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qregularexpression.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qregularexpression.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Giuseppe D'Angelo <dangelog@gmail.com>. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Giuseppe D'Angelo <dangelog@gmail.com>. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QString> #include <QStringList> @@ -355,4 +308,35 @@ QString wildcard = QRegularExpression::wildcardToRegularExpression("*.jpeg"); ("", "day", "month", "year", "", "name") //! [33] +{ +//! [34] +// using a raw string literal, R"(raw_characters)", to be able to use "\w" +// without having to escape the backslash as "\\w" +QRegularExpression re(R"(\w+)"); +QString subject("the quick fox"); +for (const QRegularExpressionMatch &match : re.globalMatch(subject)) { + // ... +} +//! [34] +} + +{ +//! [35] +// matches two digits followed by a space and a word +QRegularExpression re(R"(\d\d \w+)"); +//! [35] +} + +{ +//! [36] +QRegularExpression re("([a-z]+)|([A-Z]+)"); +QRegularExpressionMatch m = re.match("UPPERCASE"); +if (m.hasMatch()) { + qDebug() << m.hasCaptured(0); // true + qDebug() << m.hasCaptured(1); // false + qDebug() << m.hasCaptured(2); // true +} +//! [36] +} + } 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_qstring.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp index 4e79d1e27a..efb529657a 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp @@ -1,61 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -DEFINES += QT_NO_CAST_FROM_ASCII \ - QT_NO_CAST_TO_ASCII -//! [0] +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +using namespace Qt::StringLiterals; //! [1] -QString url = QLatin1String("http://www.unicode.org/"); +QString url = "https://www.unicode.org/"_L1; //! [1] @@ -81,19 +30,22 @@ if (str == QString("auto") || str == QString("extern") } //! [4] +//! [4bis] +str.append("Hello ").append("World"); +//! [4bis] //! [5] -if (str == QLatin1String("auto") - || str == QLatin1String("extern") - || str == QLatin1String("static") - || str == QLatin1String("register") { +if (str == "auto"_L1 + || str == "extern"_L1 + || str == "static"_L1 + || str == "register"_L1 { ... } //! [5] //! [6] -QLabel *label = new QLabel(QLatin1String("MOD"), this); +QLabel *label = new QLabel("MOD"_L1, this); //! [6] @@ -118,5 +70,13 @@ if (node.hasAttribute(QStringLiteral(u"http-contents-length"))) //... //! [10] //! [11] -if (attribute.name() == QLatin1String("http-contents-length")) //... +if (attribute.name() == "http-contents-length"_L1) //... //! [11] + +//! [qUtf8Printable] +qWarning("%s: %s", qUtf8Printable(key), qUtf8Printable(value)); +//! [qUtf8Printable] + +//! [qUtf16Printable] +qWarning("%ls: %ls", qUtf16Printable(key), qUtf16Printable(value)); +//! [qUtf16Printable] 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 97d28d5428..b5bfc9cd55 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QByteArray encodedString = "..."; @@ -58,7 +11,7 @@ QString string = toUtf16(encodedString); //! [1] QString string = "..."; auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); -QByteArray encodedString = fromUtf16(encodedString); +QByteArray encodedString = fromUtf16(string); //! [1] @@ -81,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_corelib_text_qstringiterator.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp index 8085e32787..10e6eb6276 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstringiterator.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QString> #include <QStringIterator> @@ -63,7 +16,7 @@ QStringIterator i(string); // implicitly converted to QStringView //! [1] while (i.hasNext()) - qDebug() << i.next(); + char32_t c = i.next(); //! [1] } diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstringview.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstringview.cpp index fc426e1977..676baa5aee 100644 --- a/src/corelib/doc/snippets/code/src_corelib_text_qstringview.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_text_qstringview.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void myfun1(QStringView sv); // preferred @@ -56,7 +9,3 @@ //! [1] void fun(QChar ch) { fun(QStringView(&ch, 1)); } //! [1] - -//! [2] - auto sv = QStringView(array, std::size(array)); // using C++17 std::size() -//! [2] diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qutf8stringview.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qutf8stringview.cpp new file mode 100644 index 0000000000..4b09796b36 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_text_qutf8stringview.cpp @@ -0,0 +1,7 @@ +// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Marc Mutz <marc.mutz@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [0] + void myfun1(QUtf8StringView sv); // preferred + void myfun2(const QUtf8StringView &sv); // compiles and works, but slower +//! [0] diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qatomic.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qatomic.cpp index 21abd2b1a0..2d55e6b706 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qatomic.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qatomic.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] MySharedType &MySharedType::operator=(const MySharedType &other) diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qexception.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qexception.cpp index 723c1630f6..74a2e4506e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qexception.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qexception.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] @@ -83,3 +36,19 @@ void MyException::raise() const { throw *this; } MyException *MyException::clone() const { return new MyException(*this); } //! [3] + +//! [4] + +try { + auto f = QtConcurrent::run([] { throw MyException {}; }); + // ... +} catch (const QUnhandledException &e) { + try { + if (e.exception()) + std::rethrow_exception(e.exception()); + } catch (const MyException &ex) { + // Process 'ex' + } +} + +//! [4] diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp index da17b390fd..500d7cc7a5 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp @@ -1,59 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QFuture<QString> future = ...; QFuture<QString>::const_iterator i; for (i = future.constBegin(); i != future.constEnd(); ++i) - cout << *i << Qt::endl; + cout << qPrintable(*i) << endl; //! [0] @@ -62,7 +15,7 @@ QFuture<QString> future; ... QFutureIterator<QString> i(future); while (i.hasNext()) - qDebug() << i.next(); + QString s = i.next(); //! [1] @@ -70,7 +23,7 @@ while (i.hasNext()) QFutureIterator<QString> i(future); i.toBack(); while (i.hasPrevious()) - qDebug() << i.previous(); + QString s = i.previous(); //! [2] //! [3] @@ -114,10 +67,10 @@ QFuture<int> future = ...; //! [5] //! [6] -QFuture<int> parentFuture = ...; -auto continuation = parentFuture.then([](int res1){ ... }).then([](int res2){ ... })... +QFuture<int> future = ...; +auto continuation = future.then([](int res1){ ... }).then([](int res2){ ... })... ... -// parentFuture throws an exception +// future throws an exception try { auto result = continuation.result(); } catch (QException &e) { @@ -252,3 +205,238 @@ auto resultFuture = testFuture.then([](int res) { // Block 6 }); //! [16] + +//! [17] +// somewhere in the main thread +auto future = QtConcurrent::run([] { + // This will run in a separate thread + ... +}).then(this, [] { + // Update UI elements +}); +//! [17] + +//! [18] +auto future = QtConcurrent::run([] { + ... +}).then(this, [] { + // Update UI elements +}).then([] { + // This will also run in the main thread +}); +//! [18] + +//! [19] +// somewhere in the main thread +auto future = QtConcurrent::run([] { + // This will run in a separate thread + ... + throw std::exception(); +}).onFailed(this, [] { + // Update UI elements +}); +//! [19] + +//! [20] +QObject *context = ...; +auto future = cachedResultsReady ? QtFuture::makeReadyValueFuture(result) + : QtConcurrent::run([] { /* compute result */}); +auto continuation = future.then(context, [] (Result result) { + // Runs in the context's thread +}).then([] { + // May or may not run in the context's thread +}); +//! [20] + +//! [21] +QFuture<int> testFuture = ...; +auto resultFuture = testFuture.then([](int res) { + // Block 1 + ... + return 1; +}).then([](int res) { + // Block 2 + ... + return 2; +}).onCanceled([] { + // Block 3 + ... + return -1; +}); +//! [21] + +//! [22] +QList<QFuture<int>> inputFutures {...}; + +// whenAll has type QFuture<QList<QFuture<int>>> +auto whenAll = QtFuture::whenAll(inputFutures.begin(), inputFutures.end()); + +// whenAllVector has type QFuture<std::vector<QFuture<int>>> +auto whenAllVector = + QtFuture::whenAll<std::vector<QFuture<int>>>(inputFutures.begin(), inputFutures.end()); +//! [22] + +//! [23] +QList<QFuture<int>> inputFutures {...}; + +QtFuture::whenAll(inputFutures.begin(), inputFutures.end()) + .then([](const QList<QFuture<int>> &results) { + for (auto future : results) { + if (future.isCanceled()) + // handle the cancellation (possibly due to an exception) + else + // do something with the result + } + }); +//! [23] + +//! [24] + +QFuture<int> intFuture = ...; +QFuture<QString> stringFuture = ...; +QFuture<void> voidFuture = ...; + +using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>; + +// whenAll has type QFuture<QList<FuturesVariant>> +auto whenAll = QtFuture::whenAll(intFuture, stringFuture, voidFuture); + +// whenAllVector has type QFuture<std::vector<FuturesVariant>> +auto whenAllVector = + QtFuture::whenAll<std::vector<FuturesVariant>>(intFuture, stringFuture, voidFuture); + +//! [24] + +//! [25] +QFuture<int> intFuture = ...; +QFuture<QString> stringFuture = ...; +QFuture<void> voidFuture = ...; + +using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>; + +QtFuture::whenAll(intFuture, stringFuture, voidFuture) + .then([](const QList<FuturesVariant> &results) { + ... + for (auto result : results) + { + // assuming handleResult() is overloaded based on the QFuture type + std::visit([](auto &&future) { handleResult(future); }, result); + } + ... + }); +//! [25] + +//! [26] +QList<QFuture<int>> inputFutures = ...; + +QtFuture::whenAny(inputFutures.begin(), inputFutures.end()) + .then([](const QtFuture::WhenAnyResult<int> &result) { + qsizetype index = result.index; + QFuture<int> future = result.future; + // ... + }); +//! [26] + +//! [27] +QFuture<int> intFuture = ...; +QFuture<QString> stringFuture = ...; +QFuture<void> voidFuture = ...; + +using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>; + +QtFuture::whenAny(intFuture, stringFuture, voidFuture).then([](const FuturesVariant &result) { + ... + // assuming handleResult() is overloaded based on the QFuture type + std::visit([](auto &&future) { handleResult(future); }, result); + ... +}); +//! [27] + +//! [28] + +QFuture<QFuture<int>> outerFuture = ...; +QFuture<int> unwrappedFuture = outerFuture.unwrap(); + +//! [28] + +//! [29] + +auto downloadImages = [] (const QUrl &url) { + QList<QImage> images; + ... + return images; +}; + +auto processImages = [](const QList<QImage> &images) { + return QtConcurrent::mappedReduced(images, scale, reduceImages); +} + +auto show = [](const QImage &image) { ... }; + +auto future = QtConcurrent::run(downloadImages, url) + .then(processImages) + .unwrap() + .then(show); +//! [29] + +//! [30] + +QFuture<QFuture<QFuture<int>>>> outerFuture; +QFuture<int> unwrappedFuture = outerFuture.unwrap(); + +//! [30] + +//! [31] +QPromise<int> p; + +QFuture<int> f1 = p.future(); +f1.then([](int) { qDebug("first"); }); + +QFuture<int> f2 = p.future(); +f2.then([](int) { qDebug("second"); }); + +p.start(); +p.addResult(42); +p.finish(); +//! [31] + +//! [32] +const std::vector<int> values{1, 2, 3}; +auto f = QtFuture::makeReadyRangeFuture(values); +//! [32] + +//! [33] +auto f = QtFuture::makeReadyRangeFuture({1, 2, 3}); +//! [33] + +//! [34] +const int count = f.resultCount(); // count == 3 +const auto results = f.results(); // results == { 1, 2, 3 } +//! [34] + +//! [35] +auto f = QtFuture::makeReadyValueFuture(std::make_unique<int>(42)); +... +const int result = *f.takeResult(); // result == 42 +//! [35] + +//! [36] +auto f = QtFuture::makeReadyVoidFuture(); +... +const bool started = f.isStarted(); // started == true +const bool running = f.isRunning(); // running == false +const bool finished = f.isFinished(); // finished == true +//! [36] + +//! [37] +QObject *context = ...; +auto future = ...; +auto continuation = future.then(context, [context](Result result) { + // ... + }).onCanceled([context = QPointer(context)] { + if (!context) + return; // context was destroyed already + // handle cancellation + }); + +//! [37] diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qfuturesynchronizer.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qfuturesynchronizer.cpp index e4624f7154..0ea226fe06 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuturesynchronizer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuturesynchronizer.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void someFunction() diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qfuturewatcher.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qfuturewatcher.cpp index d9b164b70f..b3a7747d12 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuturewatcher.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuturewatcher.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] // Instantiate the objects and connect to the finished signal. diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qmutex.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qmutex.cpp index 63897cabd4..efba262795 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qmutex.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qmutex.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] int number = 6; @@ -184,7 +137,7 @@ int complexFunction(int flag) class SignalWaiter { private: - QMutexLocker locker; + QMutexLocker<QMutex> locker; public: SignalWaiter(QMutex *mutex) diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qmutexpool.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qmutexpool.cpp deleted file mode 100644 index d9d735cdc9..0000000000 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qmutexpool.cpp +++ /dev/null @@ -1,71 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -class Number { -public: - Number(double n) : num (n) { } - - void setNumber(double n) { num = n; } - double number() const { return num; } - -private: - double num; -}; -//! [0] - - -//! [1] -void calcSquare(Number *num) -{ - QMutexLocker locker(mutexpool.get(num)); - num.setNumber(num.number() * num.number()); -} -//! [1] diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qreadwritelock.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qreadwritelock.cpp index d9abe2bc3e..3c50f991c2 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qreadwritelock.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qreadwritelock.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QReadWriteLock lock; diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp index 52105bce0b..d7c9b900af 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QSemaphore sem(5); // sem.available() == 5 @@ -82,6 +35,12 @@ sem.tryAcquire(250, 1000); // sem.available() == 5, waits 1000 milliseconds a sem.tryAcquire(3, 30000); // sem.available() == 2, returns true without waiting //! [3] +//! [tryAcquire-QDeadlineTimer] +QSemaphore sem(5); // sem.available() == 5 +sem.tryAcquire(250, QDeadlineTimer(1000)); // sem.available() == 5, waits 1000 milliseconds and returns false +sem.tryAcquire(3, QDeadlineTimer(30s)); // sem.available() == 2, returns true without waiting +//! [tryAcquire-QDeadlineTimer] + //! [4] // ... do something that may throw or return early sem.release(); diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp index 7c687a0430..9852ae4d54 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qthread.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Olivier Goffart <ogoffart@woboq.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Olivier Goffart <ogoffart@woboq.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore/QThread> class MyObject; diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp index 135a727a97..efddcd2df4 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] forever { diff --git a/src/corelib/doc/snippets/code/src_corelib_time_qdatetime.cpp b/src/corelib/doc/snippets/code/src_corelib_time_qdatetime.cpp index a477e91548..588e81bab1 100644 --- a/src/corelib/doc/snippets/code/src_corelib_time_qdatetime.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_time_qdatetime.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QDate d1(1995, 5, 17); // May 17, 1995 @@ -118,14 +71,6 @@ QTime::isValid(22, 5, 62); // returns false //! [9] -//! [10] -QTime t; -t.start(); -some_lengthy_task(); -qDebug("Time elapsed: %d ms", t.elapsed()); -//! [10] - - //! [11] QDateTime now = QDateTime::currentDateTime(); QDateTime xmas(QDate(now.date().year(), 12, 25).startOfDay()); @@ -216,3 +161,31 @@ QString string = "Tuesday, 23 April 12 22:51:41"; QString format = "dddd, d MMMM yy hh:mm:ss"; QDateTime valid = QDateTime::fromString(string, format); //! [21] + +//! [22] +// 23 April 2012: +QDate date = std::chrono::year_month_day(std::chrono::year(2012), + std::chrono::month(4), + std::chrono::day(23)); + +// Same, under `using std::chrono` convenience: +QDate dateWithLiterals1 = 23 / April / 2012y; +QDate dateWithLiterals2 = 2012y / April / 23; + +// Last day of February 2000 +QDate lastDayFeb2020 = 2000y / February / last; + +// First Monday of January 2020: +QDate firstMonday = 2020y / January / Monday[0]; + +// Last Monday of January 2020: +QDate lastMonday = 2020y / January / Monday[last]; +//! [22] + +//! [23] +QDateTime local(QDateTime::currentDateTime()); +QDateTime UTC(local.toTimeSpec(QTimeZone::UTC)); +qDebug() << "Local time is:" << local; +qDebug() << "UTC time is:" << UTC; +qDebug() << "No difference between times represented:" << local.secsTo(UTC); +//! [23] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qbitarray.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qbitarray.cpp index a436dcb358..7c98b6d8ff 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qbitarray.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbitarray.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QBitArray ba(200); diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp index 1871666a56..dbc83127ec 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 David Faure <faure@kde.org> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 David Faure <faure@kde.org> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QCommandLineOption> #include <QCommandLineParser> diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp index a5ce172e71..cc22ba88ce 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 David Faure <faure@kde.org> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 David Faure <faure@kde.org> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <qcommandlineparser.h> @@ -137,12 +90,4 @@ Arguments: //! [3] } -{ -//! [4] -QCommandLineParser parser; -parser.setApplicationDescription(QCoreApplication::translate("main", "The best application in the world")); -parser.addHelpOption(); -//! [4] -} - } diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp index 159d8f4a42..7c06e36313 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 David Faure <faure@kde.org> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 David Faure <faure@kde.org> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <qcommandlineparser.h> diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp index 84780374e9..891ec1f549 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] MyRecord record(int row) const diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qeasingcurve.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qeasingcurve.cpp index 88f1e90713..e0be0c3d9a 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qeasingcurve.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qeasingcurve.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [typedef] qreal myEasingFunction(qreal progress); diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp index 344fbb241d..c779b9e3e7 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QHash<QString, int> hash; @@ -89,7 +42,7 @@ QHash<int, QWidget *> hash; ... for (int i = 0; i < 1000; ++i) { if (hash[i] == okButton) - cout << "Found button at index " << i << Qt::endl; + cout << "Found button at index " << i << endl; } //! [6] @@ -98,17 +51,14 @@ for (int i = 0; i < 1000; ++i) { QHashIterator<QString, int> i(hash); while (i.hasNext()) { i.next(); - cout << i.key() << ": " << i.value() << Qt::endl; + cout << qPrintable(i.key()) << ": " << i.value() << endl; } //! [7] //! [8] -QHash<QString, int>::const_iterator i = hash.constBegin(); -while (i != hash.constEnd()) { - cout << i.key() << ": " << i.value() << Qt::endl; - ++i; -} +for (auto i = hash.cbegin(), end = hash.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; //! [8] @@ -122,8 +72,8 @@ hash.insert("plenty", 2000); //! [12] QHash<QString, int> hash; ... -foreach (int value, hash) - cout << value << Qt::endl; +for (int value : std::as_const(hash)) + cout << value << endl; //! [12] @@ -185,7 +135,7 @@ QHash<QString, int> hash; ... QHash<QString, int>::const_iterator i = hash.find("HDR"); while (i != hash.end() && i.key() == "HDR") { - cout << i.value() << Qt::endl; + cout << i.value() << endl; ++i; } //! [16] @@ -198,50 +148,20 @@ hash.insert("February", 2); ... hash.insert("December", 12); -QHash<QString, int>::iterator i; -for (i = hash.begin(); i != hash.end(); ++i) - cout << i.key() << ": " << i.value() << Qt::endl; +for (auto i = hash.cbegin(), end = hash.cend(); i != end; ++i) + cout << qPrintable(key()) << ": " << i.value() << endl; //! [17] //! [18] -QHash<QString, int>::iterator i; -for (i = hash.begin(); i != hash.end(); ++i) +for (auto i = hash.begin(), end = hash.end(); i != end; ++i) i.value() += 2; //! [18] - -//! [19] -QHash<QString, int>::iterator i = hash.begin(); -while (i != hash.end()) { - if (i.key().startsWith('_')) - i = hash.erase(i); - else - ++i; -} -//! [19] - - -//! [20] -QHash<QString, int>::iterator i = hash.begin(); -while (i != hash.end()) { - QHash<QString, int>::iterator prev = i; - ++i; - if (prev.key().startsWith('_')) - hash.erase(prev); -} -//! [20] - - //! [21] -// WRONG -while (i != hash.end()) { - if (i.key().startsWith('_')) - hash.erase(i); - ++i; -} +erase_if(hash, [](const QHash<QString, int>::iterator it) { return it.value() > 10; }); //! [21] - +} //! [22] if (i.key() == "Hello") @@ -256,9 +176,8 @@ hash.insert("February", 2); ... hash.insert("December", 12); -QHash<QString, int>::const_iterator i; -for (i = hash.constBegin(); i != hash.constEnd(); ++i) - cout << i.key() << ": " << i.value() << Qt::endl; +for (auto i = hash.cbegin(), end = hash.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; //! [23] @@ -279,24 +198,24 @@ hash3 = hash1 + hash2; //! [25] QList<int> values = hash.values("plenty"); -for (int i = 0; i < values.size(); ++i) - cout << values.at(i) << Qt::endl; +for (auto i : std::as_const(values)) + cout << i << endl; //! [25] //! [26] -QMultiHash<QString, int>::iterator i = hash.find("plenty"); -while (i != hash.end() && i.key() == "plenty") { - cout << i.value() << Qt::endl; +auto i = hash.constFind("plenty"); +while (i != hash.cend() && i.key() == "plenty") { + cout << i.value() << endl; ++i; } //! [26] //! [27] -for (QHash<int, QString>::const_iterator it = hash.cbegin(), end = hash.cend(); it != end; ++it) { - cout << "The key: " << it.key() << Qt::endl - cout << "The value: " << it.value() << Qt::endl; - cout << "Also the value: " << (*it) << Qt::endl; +for (auto it = hash.cbegin(), end = hash.cend(); it != end; ++it) { + cout << "The key: " << it.key() << endl; + cout << "The value: " << qPrintable(it.value()) << endl; + cout << "Also the value: " << qPrintable(*it) << endl; } //! [27] @@ -335,10 +254,6 @@ inline size_t qHash(const std::unordered_set<int> &key, size_t seed = 0) } //! [qhashrangecommutative] -//! [29] -qHash(qMakePair(key.first, key.second), seed); -//! [29] - //! [30] {0, 1, 2} //! [30] @@ -348,9 +263,45 @@ qHash(qMakePair(key.first, key.second), seed); //! [31] //! [32] -size_t qHash(K key); -size_t qHash(const K &key); - size_t qHash(K key, size_t seed); size_t qHash(const K &key, size_t seed); + +size_t qHash(K key); // deprecated, do not use +size_t qHash(const K &key); // deprecated, do not use //! [32] + +//! [33] +namespace std { +template <> struct hash<K> +{ + // seed is optional + size_t operator()(const K &key, size_t seed = 0) const; +}; +} +//! [33] + +//! [34] +QHash<QString, int> hash; +hash.insert("January", 1); +hash.insert("February", 2); +// ... +hash.insert("December", 12); + +for (auto [key, value] : hash.asKeyValueRange()) { + cout << qPrintable(key) << ": " << value << endl; + --value; // convert to JS month indexing +} +//! [34] + +//! [35] +QMultiHash<QString, int> hash; +hash.insert("January", 1); +hash.insert("February", 2); +// ... +hash.insert("December", 12); + +for (auto [key, value] : hash.asKeyValueRange()) { + cout << qPrintable(key) << ": " << value << endl; + --value; // convert to JS month indexing +} +//! [35] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qlist.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qlist.cpp index e959915c5e..499e8fe480 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qlist.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qlist.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QList<int> integerList; @@ -71,24 +24,24 @@ if (list[0] == "Liz") //! [4] -for (int i = 0; i < list.size(); ++i) { +for (qsizetype i = 0; i < list.size(); ++i) { if (list.at(i) == "Alfonso") - cout << "Found Alfonso at position " << i << Qt::endl; + cout << "Found Alfonso at position " << i << endl; } //! [4] //! [5] -int i = list.indexOf("Harumi"); +qsizetype i = list.indexOf("Harumi"); if (i != -1) - cout << "First occurrence of Harumi is at position " << i << Qt::endl; + cout << "First occurrence of Harumi is at position " << i << endl; //! [5] //! [6] QList<int> list(10); int *data = list.data(); -for (int i = 0; i < 10; ++i) +for (qsizetype i = 0; i < 10; ++i) data[i] = 2 * i; //! [6] @@ -148,16 +101,14 @@ list.prepend("three"); //! [9] -QList<QString> list; -list << "alpha" << "beta" << "delta"; +QList<QString> list = {"alpha", "beta", "delta"}; list.insert(2, "gamma"); // list: ["alpha", "beta", "gamma", "delta"] //! [9] //! [10] -QList<double> list; -list << 2.718 << 1.442 << 0.4342; +QList<double> list = {2.718, 1.442, 0.4342}; list.insert(1, 3, 9.9); // list: [2.718, 9.9, 9.9, 9.9, 1.442, 0.4342] //! [10] @@ -174,8 +125,7 @@ list.fill("oh", 5); //! [12] -QList<QString> list; -list << "A" << "B" << "C" << "B" << "A"; +QList<QString> list{"A", "B", "C", "B", "A"}; list.indexOf("B"); // returns 1 list.indexOf("B", 1); // returns 1 list.indexOf("B", 2); // returns 3 @@ -184,27 +134,9 @@ list.indexOf("X"); // returns -1 //! [13] -QList<QString> list; -list << "A" << "B" << "C" << "B" << "A"; +QList<QString> list = {"A", "B", "C", "B", "A"}; list.lastIndexOf("B"); // returns 3 list.lastIndexOf("B", 3); // returns 3 list.lastIndexOf("B", 2); // returns 1 list.lastIndexOf("X"); // returns -1 //! [13] - -//! [16] -std::vector<double> stdvector; -stdvector.push_back(1.2); -stdvector.push_back(0.5); -stdvector.push_back(3.14); - -QList<double> list = QList<double>::fromStdVector(stdvector); -//! [16] - - -//! [17] -QList<double> list; -list << 1.2 << 0.5 << 3.14; - -std::vector<double> stdvector = list.toStdVector(); -//! [17] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qmap.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qmap.cpp index 145cd10d84..5f87211968 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qmap.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qmap.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QMap<QString, int> map; @@ -89,7 +42,7 @@ QMap<int, QWidget *> map; ... for (int i = 0; i < 1000; ++i) { if (map[i] == okButton) - cout << "Found button at index " << i << Qt::endl; + cout << "Found button at index " << i << endl; } //! [6] @@ -98,17 +51,14 @@ for (int i = 0; i < 1000; ++i) { QMapIterator<QString, int> i(map); while (i.hasNext()) { i.next(); - cout << i.key() << ": " << i.value() << Qt::endl; + cout << qPrintable(i.key()) << ": " << i.value() << endl; } //! [7] //! [8] -QMap<QString, int>::const_iterator i = map.constBegin(); -while (i != map.constEnd()) { - cout << i.key() << ": " << i.value() << Qt::endl; - ++i; -} +for (auto i = map.cbegin(), end = map.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; //! [8] @@ -119,27 +69,11 @@ map.insert("plenty", 2000); //! [9] -//! [10] -QList<int> values = map.values("plenty"); -for (int i = 0; i < values.size(); ++i) - cout << values.at(i) << Qt::endl; -//! [10] - - -//! [11] -QMap<QString, int>::iterator i = map.find("plenty"); -while (i != map.end() && i.key() == "plenty") { - cout << i.value() << Qt::endl; - ++i; -} -//! [11] - - //! [12] QMap<QString, int> map; ... -foreach (int value, map) - cout << value << Qt::endl; +for (int value : std::as_const(map)) + cout << value << endl; //! [12] @@ -170,43 +104,6 @@ inline bool operator<(const Employee &e1, const Employee &e2) //! [13] -//! [14] -QMap<QString, int> map; -... -QMap<QString, int>::const_iterator i = map.find("HDR"); -while (i != map.end() && i.key() == "HDR") { - cout << i.value() << Qt::endl; - ++i; -} -//! [14] - - -//! [15] -QMap<int, QString> map; -map.insert(1, "one"); -map.insert(5, "five"); -map.insert(10, "ten"); - -map.lowerBound(0); // returns iterator to (1, "one") -map.lowerBound(1); // returns iterator to (1, "one") -map.lowerBound(2); // returns iterator to (5, "five") -map.lowerBound(10); // returns iterator to (10, "ten") -map.lowerBound(999); // returns end() -//! [15] - - -//! [16] -QMap<QString, int> map; -... -QMap<QString, int>::const_iterator i = map.lowerBound("HDR"); -QMap<QString, int>::const_iterator upperBound = map.upperBound("HDR"); -while (i != upperBound) { - cout << i.value() << Qt::endl; - ++i; -} -//! [16] - - //! [17] QMap<int, QString> map; map.insert(1, "one"); @@ -228,50 +125,33 @@ map.insert("February", 2); ... map.insert("December", 12); -QMap<QString, int>::iterator i; -for (i = map.begin(); i != map.end(); ++i) - cout << i.key() << ": " << i.value() << Qt::endl; +for (auto i = map.cbegin(), end = map.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; //! [18] //! [19] -QMap<QString, int>::iterator i; -for (i = map.begin(); i != map.end(); ++i) +for (auto i = map.begin(), end = map.end(); i != end; ++i) i.value() += 2; //! [19] +void erase() +{ +QMap<QString, int> map; //! [20] -QMap<QString, int>::iterator i = map.begin(); -while (i != map.end()) { - if (i.key().startsWith('_')) +QMap<QString, int>::const_iterator i = map.cbegin(); +while (i != map.cend()) { + if (i.value() > 10) i = map.erase(i); else ++i; } //! [20] - - //! [21] -QMap<QString, int>::iterator i = map.begin(); -while (i != map.end()) { - QMap<QString, int>::iterator prev = i; - ++i; - if (prev.key().startsWith('_')) - map.erase(prev); -} +erase_if(map, [](const QMap<QString, int>::iterator it) { return it.value() > 10; }); //! [21] - - -//! [22] -// WRONG -while (i != map.end()) { - if (i.key().startsWith('_')) - map.erase(i); - ++i; } -//! [22] - //! [23] if (i.key() == "Hello") @@ -286,47 +166,16 @@ map.insert("February", 2); ... map.insert("December", 12); -QMap<QString, int>::const_iterator i; -for (i = map.constBegin(); i != map.constEnd(); ++i) - cout << i.key() << ": " << i.value() << Qt::endl; +for (auto i = map.cbegin(), end = map.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; //! [24] -//! [25] -QMultiMap<QString, int> map1, map2, map3; - -map1.insert("plenty", 100); -map1.insert("plenty", 2000); -// map1.size() == 2 - -map2.insert("plenty", 5000); -// map2.size() == 1 - -map3 = map1 + map2; -// map3.size() == 3 -//! [25] - - -//! [26] -QList<int> values = map.values("plenty"); -for (int i = 0; i < values.size(); ++i) - cout << values.at(i) << Qt::endl; -//! [26] - - -//! [27] -QMultiMap<QString, int>::iterator i = map.find("plenty"); -while (i != map.end() && i.key() == "plenty") { - cout << i.value() << Qt::endl; - ++i; -} -//! [27] - //! [keyiterator1] for (QMap<int, QString>::const_iterator it = map.cbegin(), end = map.cend(); it != end; ++it) { - cout << "The key: " << it.key() << Qt::endl - cout << "The value: " << it.value() << Qt::endl; - cout << "Also the value: " << (*it) << Qt::endl; + cout << "The key: " << it.key() << endl; + cout << "The value: " << qPrintable(it.value()) << endl; + cout << "Also the value: " << qPrintable(*it) << endl; } //! [keyiterator1] @@ -340,3 +189,16 @@ qDeleteAll(map2.keys()); int numPrimes = std::count_if(map.keyBegin(), map.keyEnd(), isPrimeNumber); qDeleteAll(map2.keyBegin(), map2.keyEnd()); //! [keyiterator2] + +//! [28] +QMap<QString, int> map; +map.insert("January", 1); +map.insert("February", 2); +// ... +map.insert("December", 12); + +for (auto [key, value] : map.asKeyValueRange()) { + cout << qPrintable(key) << ": " << value << endl; + --value; // convert to JS month indexing +} +//! [28] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qmultimap.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qmultimap.cpp new file mode 100644 index 0000000000..42ec46585b --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qmultimap.cpp @@ -0,0 +1,256 @@ +// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [0] +QMultiMap<QString, int> multimap; +//! [0] + + +//! [2] +multimap.insert("a", 1); +multimap.insert("b", 3); +multimap.insert("c", 7); +multimap.insert("c", -5); +//! [2] + + +//! [3] +int num2 = multimap.value("a"); // 1 +int num3 = multimap.value("thirteen"); // not found; 0 +int num3 = 0; +auto it = multimap.constFind("b"); +if (it != multimap.cend()) { + num3 = it.value(); +} +//! [3] + + +//! [4] +int timeout = 30; +if (multimap.contains("TIMEOUT")) + timeout = multimap.value("TIMEOUT"); + +// better: +auto it = multimap.find("TIMEOUT"); +if (it != multimap.end()) + timeout = it.value(); +//! [4] + + +//! [5] +int timeout = multimap.value("TIMEOUT", 30); +//! [5] + + +//! [7] +QMultiMapIterator<QString, int> i(multimap); +while (i.hasNext()) { + i.next(); + cout << qPrintable(i.key()) << ": " << i.value() << endl; +} +//! [7] + + +//! [8] +for (auto i = multimap.cbegin(), end = multimap.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; +//! [8] + + +//! [9] +multimap.insert("plenty", 100); +multimap.insert("plenty", 2000); +// multimap.size() == 2 +//! [9] + + +//! [10] +QList<int> values = multimap.values("plenty"); +for (auto i : std::as_const(values)) + cout << i << endl; +//! [10] + + +//! [11] +auto i = multimap.find("plenty"); +while (i != map.end() && i.key() == "plenty") { + cout << i.value() << endl; + ++i; +} + +// better: +auto [i, end] = multimap.equal_range("plenty"); +while (i != end) { + cout << i.value() << endl; + ++i; +} +//! [11] + + +//! [12] +QMap<QString, int> multimap; +... +for (int value : std::as_const(multimap)) + cout << value << endl; +//! [12] + + +//! [13] +#ifndef EMPLOYEE_H +#define EMPLOYEE_H + +class Employee +{ +public: + Employee() {} + Employee(const QString &name, QDate dateOfBirth); + ... + +private: + QString myName; + QDate myDateOfBirth; +}; + +inline bool operator<(const Employee &e1, const Employee &e2) +{ + if (e1.name() != e2.name()) + return e1.name() < e2.name(); + return e1.dateOfBirth() < e2.dateOfBirth(); +} + +#endif // EMPLOYEE_H +//! [13] + + +//! [15] +QMultiMap<int, QString> multimap; +multimap.insert(1, "one"); +multimap.insert(5, "five"); +multimap.insert(5, "five (2)"); +multimap.insert(10, "ten"); + +multimap.lowerBound(0); // returns iterator to (1, "one") +multimap.lowerBound(1); // returns iterator to (1, "one") +multimap.lowerBound(2); // returns iterator to (5, "five") +multimap.lowerBound(5); // returns iterator to (5, "five") +multimap.lowerBound(6); // returns iterator to (10, "ten") +multimap.lowerBound(10); // returns iterator to (10, "ten") +multimap.lowerBound(999); // returns end() +//! [15] + + +//! [16] +QMap<QString, int> multimap; +... +QMap<QString, int>::const_iterator i = multimap.lowerBound("HDR"); +QMap<QString, int>::const_iterator upperBound = multimap.upperBound("HDR"); +while (i != upperBound) { + cout << i.value() << endl; + ++i; +} +//! [16] + + +//! [17] +QMultiMap<int, QString> multimap; +multimap.insert(1, "one"); +multimap.insert(5, "five"); +multimap.insert(5, "five (2)"); +multimap.insert(10, "ten"); + +multimap.upperBound(0); // returns iterator to (1, "one") +multimap.upperBound(1); // returns iterator to (5, "five") +multimap.upperBound(2); // returns iterator to (5, "five") +multimap.lowerBound(5); // returns iterator to (5, "five (2)") +multimap.lowerBound(6); // returns iterator to (10, "ten") +multimap.upperBound(10); // returns end() +multimap.upperBound(999); // returns end() +//! [17] + +//! [19] +for (auto it = multimap.begin(), end = multimap.end(); i != end; ++i) + i.value() += 2; +//! [19] + +void erase() +{ +QMultiMap<QString, int> multimap; +//! [20] +QMultiMap<QString, int>::const_iterator i = multimap.cbegin(); +while (i != multimap.cend()) { + if (i.value() > 10) + i = multimap.erase(i); + else + ++i; +} +//! [20] +//! [21] +erase_if(multimap, [](const QMultiMap<QString, int>::iterator it) { return it.value() > 10; }); +//! [21] +} + + +//! [23] +if (i.key() == "Hello") + i.value() = "Bonjour"; +//! [23] + + +//! [24] +QMultiMap<QString, int> multi; +multimap.insert("January", 1); +multimap.insert("February", 2); +... +multimap.insert("December", 12); + +for (auto i = multimap.cbegin(), end = multimap.cend(); i != end; ++i) + cout << qPrintable(i.key()) << ": " << i.value() << endl; +//! [24] + + +//! [25] +QMultiMap<QString, int> map1, map2, map3; + +map1.insert("plenty", 100); +map1.insert("plenty", 2000); +// map1.size() == 2 + +map2.insert("plenty", 5000); +// map2.size() == 1 + +map3 = map1 + map2; +// map3.size() == 3 +//! [25] + +//! [keyiterator1] +for (auto it = multimap.cbegin(), end = multimap.cend(); it != end; ++it) { + cout << "The key: " << it.key() << endl + cout << "The value: " << qPrintable(it.value()) << endl; + cout << "Also the value: " << qPrintable(*it) << endl; +} +//! [keyiterator1] + +//! [keyiterator2] +// Inefficient, keys() is expensive +QList<int> keys = multimap.keys(); +int numPrimes = std::count_if(multimap.cbegin(), multimap.cend(), isPrimeNumber); +qDeleteAll(multimap2.keys()); + +// Efficient, no memory allocation needed +int numPrimes = std::count_if(multimap.keyBegin(), multimap.keyEnd(), isPrimeNumber); +qDeleteAll(multimap2.keyBegin(), multimap2.keyEnd()); +//! [keyiterator2] + +//! [26] +QMultiMap<QString, int> map; +map.insert("January", 1); +map.insert("February", 2); +// ... +map.insert("December", 12); + +for (auto [key, value] : map.asKeyValueRange()) { + cout << qPrintable(key) << ": " << value << endl; + --value; // convert to JS month indexing +} +//! [26] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qpoint.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qpoint.cpp index fd4db5580f..f7c06c17cc 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qpoint.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qpoint.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QPoint p; @@ -92,7 +45,7 @@ p *= 2.5; // p becomes (-3, 10) //! [16] QPoint p( 3, 7); QPoint q(-1, 4); -int lengthSquared = QPoint::dotProduct(p, q); // lengthSquared becomes 25 +int dotProduct = QPoint::dotProduct(p, q); // dotProduct becomes 25 //! [16] @@ -169,5 +122,5 @@ p /= 2.5; // p becomes (-1.1, 4.1) //! [17] QPointF p( 3.1, 7.1); QPointF q(-1.0, 4.1); -int lengthSquared = QPointF::dotProduct(p, q); // lengthSquared becomes 26.01 +qreal dotProduct = QPointF::dotProduct(p, q); // dotProduct becomes 26.01 //! [17] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qqueue.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qqueue.cpp index 6046c73b0f..c59ec1060a 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qqueue.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qqueue.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QQueue<int> queue; @@ -54,5 +7,5 @@ queue.enqueue(1); queue.enqueue(2); queue.enqueue(3); while (!queue.isEmpty()) - cout << queue.dequeue() << Qt::endl; + cout << queue.dequeue() << endl; //! [0] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp index a19dc086ac..403d188806 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QRect r1(100, 200, 11, 16); diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qscopedpointer.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qscopedpointer.cpp index dde9a92129..ee0e9eafa1 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qscopedpointer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qscopedpointer.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void myFunction(bool useSubClass) @@ -122,7 +75,7 @@ public: private: Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators - // are now disabled, so the compiler won't implicitely + // are now disabled, so the compiler won't implicitly // generate them. }; //! [4] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qscopeguard.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qscopeguard.cpp index 2fa4f88011..8a0d8a8012 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qscopeguard.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qscopeguard.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Sérgio Martins <sergio.martins@kdab.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Sérgio Martins <sergio.martins@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void myComplexCodeWithMultipleReturnPoints(int v) diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp index 88c8ae4151..2c8ca411f7 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] class EmployeeData; diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp index e2979fa7b4..fd0612590e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2018 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] class Y: public QEnableSharedFromThis<Y> diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qsize.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qsize.cpp index e1caf867b3..ee3b7b3268 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qsize.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qsize.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QSize t1(10, 12); diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qtimeline.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qtimeline.cpp index 80859d5ba5..39bcd4faf0 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qtimeline.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qtimeline.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] ... diff --git a/src/corelib/doc/snippets/code/src_corelib_xml_qxmlstream.cpp b/src/corelib/doc/snippets/code/src_corelib_xml_qxmlstream.cpp index 174c10bd4c..fe95b9939a 100644 --- a/src/corelib/doc/snippets/code/src_corelib_xml_qxmlstream.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_xml_qxmlstream.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QXmlStreamReader xml; diff --git a/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp b/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp deleted file mode 100644 index 82f916581e..0000000000 --- a/src/corelib/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp +++ /dev/null @@ -1,158 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] -int ret = QMessageBox::warning(this, tr("My Application"), - tr("The document has been modified.\n" - "Do you want to save your changes?"), - QMessageBox::Save | QMessageBox::Discard - | QMessageBox::Cancel, - QMessageBox::Save); -//! [0] - - -//! [1] -QMessageBox msgBox; -msgBox.setStandardButtons(QMessageBox::Yes | QMessageBox::No); -switch (msgBox.exec()) { -case QMessageBox::Yes: - // yes was clicked - break; -case QMessageBox::No: - // no was clicked - break; -default: - // should never be reached - break; -} -//! [1] - - -//! [2] -QMessageBox msgBox; -QPushButton *connectButton = msgBox.addButton(tr("Connect"), QMessageBox::ActionRole); -QPushButton *abortButton = msgBox.addButton(QMessageBox::Abort); - -msgBox.exec(); - -if (msgBox.clickedButton() == connectButton) { - // connect -} else if (msgBox.clickedButton() == abortButton) { - // abort -} -//! [2] - - -//! [3] -QMessageBox messageBox(this); -QAbstractButton *disconnectButton = - messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole); -... -messageBox.exec(); -if (messageBox.clickedButton() == disconnectButton) { - ... -} -//! [3] - - -//! [4] -#include <QApplication> -#include <QMessageBox> - -int main(int argc, char *argv[]) -{ - QT_REQUIRE_VERSION(argc, argv, "4.0.2") - - QApplication app(argc, argv); - ... - return app.exec(); -} -//! [4] - -//! [5] -QMessageBox msgBox; -msgBox.setText("The document has been modified."); -msgBox.exec(); -//! [5] - -//! [6] -QMessageBox msgBox; -msgBox.setText("The document has been modified."); -msgBox.setInformativeText("Do you want to save your changes?"); -msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel); -msgBox.setDefaultButton(QMessageBox::Save); -int ret = msgBox.exec(); -//! [6] - -//! [7] -switch (ret) { - case QMessageBox::Save: - // Save was clicked - break; - case QMessageBox::Discard: - // Don't Save was clicked - break; - case QMessageBox::Cancel: - // Cancel was clicked - break; - default: - // should never be reached - break; -} -//! [7] - -//! [9] -QMessageBox msgBox(this); -msgBox.setText(tr("The document has been modified.\n" - "Do you want to save your changes?")); -msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard - | QMessageBox::Cancel); -msgBox.setDefaultButton(QMessageBox::Save); -//! [9] 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 c1af521c03..4ef1891cdb 100644 --- a/src/corelib/doc/snippets/code/src_gui_itemviews_qidentityproxymodel.cpp +++ b/src/corelib/doc/snippets/code/src_gui_itemviews_qidentityproxymodel.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Stephen Kelly <stephen.kelly@kdab.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Stephen Kelly <stephen.kelly@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] class DateFormatProxyModel : public QIdentityProxyModel @@ -64,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/code/src_gui_itemviews_qitemselectionmodel.cpp b/src/corelib/doc/snippets/code/src_gui_itemviews_qitemselectionmodel.cpp index 544e0f5309..0647f7f1c4 100644 --- a/src/corelib/doc/snippets/code/src_gui_itemviews_qitemselectionmodel.cpp +++ b/src/corelib/doc/snippets/code/src_gui_itemviews_qitemselectionmodel.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QItemSelection *selection = new QItemSelection(topLeft, bottomRight); 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/eventfilters/filterobject.cpp b/src/corelib/doc/snippets/eventfilters/filterobject.cpp index abe72c2045..385620f97f 100644 --- a/src/corelib/doc/snippets/eventfilters/filterobject.cpp +++ b/src/corelib/doc/snippets/eventfilters/filterobject.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> diff --git a/src/corelib/doc/snippets/eventfilters/filterobject.h b/src/corelib/doc/snippets/eventfilters/filterobject.h index 354aa4ff5c..7da2dae2f6 100644 --- a/src/corelib/doc/snippets/eventfilters/filterobject.h +++ b/src/corelib/doc/snippets/eventfilters/filterobject.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #ifndef FILTEROBJECT_H #define FILTEROBJECT_H @@ -58,7 +11,7 @@ class FilterObject : public QObject Q_OBJECT public: - FilterObject(QObject *parent = 0); + FilterObject(QObject *parent = nullptr); bool eventFilter(QObject *object, QEvent *event) override; void setFilteredObject(QObject *object); diff --git a/src/corelib/doc/snippets/eventfilters/main.cpp b/src/corelib/doc/snippets/eventfilters/main.cpp index e7112ab1f5..f4f58b3300 100644 --- a/src/corelib/doc/snippets/eventfilters/main.cpp +++ b/src/corelib/doc/snippets/eventfilters/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QTextEdit> diff --git a/src/corelib/doc/snippets/events/events.cpp b/src/corelib/doc/snippets/events/events.cpp index 969b0047f0..faeb168d80 100644 --- a/src/corelib/doc/snippets/events/events.cpp +++ b/src/corelib/doc/snippets/events/events.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QCheckBox> #include <QMouseEvent> diff --git a/src/corelib/doc/snippets/file/file.cpp b/src/corelib/doc/snippets/file/file.cpp index ed398984d4..d1244f4bf2 100644 --- a/src/corelib/doc/snippets/file/file.cpp +++ b/src/corelib/doc/snippets/file/file.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QFile> #include <QTextStream> diff --git a/src/corelib/doc/snippets/fileinfo/main.cpp b/src/corelib/doc/snippets/fileinfo/main.cpp index 6852a36af5..819bde3de5 100644 --- a/src/corelib/doc/snippets/fileinfo/main.cpp +++ b/src/corelib/doc/snippets/fileinfo/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QPushButton> @@ -78,14 +31,16 @@ int main(int argc, char *argv[]) qDebug() << fileInfo5.fileName(); qDebug() << fileInfo6.fileName(); + QGroupBox *groupBox = new QGroupBox(QStringLiteral("QFileInfo::dir() test")); + + QVBoxLayout *vbox = new QVBoxLayout(groupBox); + QPushButton* button1 = new QPushButton(fileInfo1.dir().path()); QPushButton* button2 = new QPushButton(fileInfo2.dir().path()); QPushButton* button3 = new QPushButton(fileInfo3.dir().path()); QPushButton* button4 = new QPushButton(fileInfo4.dir().path()); QPushButton* button5 = new QPushButton(fileInfo5.dir().path()); QPushButton* button6 = new QPushButton(fileInfo6.dir().path()); - - QVBoxLayout* vbox = new QVBoxLayout; vbox->addWidget(button1); vbox->addWidget(button2); vbox->addWidget(button3); @@ -94,8 +49,6 @@ int main(int argc, char *argv[]) vbox->addWidget(button6); vbox->addStretch(1); - QGroupBox *groupBox = new QGroupBox("QFileInfo::dir() test"); - groupBox->setLayout(vbox); groupBox->show(); return app.exec(); diff --git a/src/corelib/doc/snippets/hellotrmain.cpp b/src/corelib/doc/snippets/hellotrmain.cpp index 526da44701..d780f19117 100644 --- a/src/corelib/doc/snippets/hellotrmain.cpp +++ b/src/corelib/doc/snippets/hellotrmain.cpp @@ -1,52 +1,7 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +using namespace Qt::StringLiterals; //! [0] int main(int argc, char *argv[]) @@ -55,7 +10,7 @@ int main(int argc, char *argv[]) QTranslator translator; // look up e.g. :/i18n/myapp_de.qm - if (translator.load(QLocale(), QLatin1String("myapp"), QLatin1String("_"), QLatin1String(":/i18n"))) + if (translator.load(QLocale(), "myapp"_L1, "_"_L1, ":/i18n"_L1)) QCoreApplication::installTranslator(&translator); QPushButton hello(QCoreApplication::translate("main", "Hello world!")); diff --git a/src/corelib/doc/snippets/jni/src_qjniobject.cpp b/src/corelib/doc/snippets/jni/src_qjniobject.cpp new file mode 100644 index 0000000000..6e66b51383 --- /dev/null +++ b/src/corelib/doc/snippets/jni/src_qjniobject.cpp @@ -0,0 +1,63 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [QJniObject scope] +void functionScope() +{ + QString helloString("Hello"); + jstring myJString = 0; + { + QJniObject string = QJniObject::fromString(helloString); + myJString = string.object<jstring>(); + } + + // Ops! myJString is no longer valid. +} +//! [QJniObject scope] + +//! [C++ native methods] +static void fromJavaOne(JNIEnv *env, jobject thiz, jint x) +{ + Q_UNUSED(env); + Q_UNUSED(thiz); + qDebug() << x << "< 100"; +} + +static void fromJavaTwo(JNIEnv *env, jobject thiz, jint x) +{ + Q_UNUSED(env); + Q_UNUSED(thiz); + qDebug() << x << ">= 100"; +} + +void foo() +{ + // register the native methods first, ideally it better be done with the app start + const JNINativeMethod methods[] = + {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)}, + {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}}; + QJniEnvironment env; + env.registerNativeMethods("my/java/project/FooJavaClass", methods, 2); + + // Call the java method which will calls back to the C++ functions + QJniObject::callStaticMethod<void>("my/java/project/FooJavaClass", "foo", "(I)V", 10); // Output: 10 < 100 + QJniObject::callStaticMethod<void>("my/java/project/FooJavaClass", "foo", "(I)V", 100); // Output: 100 >= 100 +} +//! [C++ native methods] + +//! [Java native methods] +class FooJavaClass +{ + public static void foo(int x) + { + if (x < 100) + callNativeOne(x); + else + callNativeTwo(x); + } + +private static native void callNativeOne(int x); +private static native void callNativeTwo(int x); + +} +//! [Java native methods] diff --git a/src/corelib/doc/snippets/ntfsp.cpp b/src/corelib/doc/snippets/ntfsp.cpp index 099480302f..18f9bd0c5e 100644 --- a/src/corelib/doc/snippets/ntfsp.cpp +++ b/src/corelib/doc/snippets/ntfsp.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] @@ -58,3 +11,18 @@ qt_ntfs_permission_lookup++; // turn checking on qt_ntfs_permission_lookup--; // turn it off again //! [1] +//! [raii] +void complexFunction() +{ + QNtfsPermissionCheckGuard permissionGuard; // check is enabled + + // do complex things here that need permission check enabled + +} // as the guard goes out of scope the check is disabled +//! [raii] + +//! [free-funcs] +qAreNtfsPermissionChecksEnabled(); // check status +qEnableNtfsPermissionChecks(); // turn checking on +qDisableNtfsPermissionChecks(); // turn it off again +//! [free-funcs] diff --git a/src/corelib/doc/snippets/overview/using-qt-core.cmake b/src/corelib/doc/snippets/overview/using-qt-core.cmake index a5f43c1472..6e4b8d8028 100644 --- a/src/corelib/doc/snippets/overview/using-qt-core.cmake +++ b/src/corelib/doc/snippets/overview/using-qt-core.cmake @@ -1,2 +1,2 @@ -find_package(Qt5 COMPONENTS Core REQUIRED) -target_link_libraries(mytarget Qt5::Core) +find_package(Qt6 REQUIRED COMPONENTS Core) +target_link_libraries(mytarget PRIVATE Qt6::Core) diff --git a/src/corelib/doc/snippets/pointer/pointer.cpp b/src/corelib/doc/snippets/pointer/pointer.cpp index 40c86d4fb2..2cc4529b85 100644 --- a/src/corelib/doc/snippets/pointer/pointer.cpp +++ b/src/corelib/doc/snippets/pointer/pointer.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QLabel> diff --git a/src/corelib/doc/snippets/process/process.cpp b/src/corelib/doc/snippets/process/process.cpp index 0449ee221c..ad7e4883e9 100644 --- a/src/corelib/doc/snippets/process/process.cpp +++ b/src/corelib/doc/snippets/process/process.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QProcess> diff --git a/src/corelib/doc/snippets/qbytearraylist/main.cpp b/src/corelib/doc/snippets/qbytearraylist/main.cpp index fd52ef945b..d2164f326c 100644 --- a/src/corelib/doc/snippets/qbytearraylist/main.cpp +++ b/src/corelib/doc/snippets/qbytearraylist/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2014 by Southwest Research Institute (R) -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2014 by Southwest Research Institute (R) +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QByteArrayList> diff --git a/src/corelib/doc/snippets/qbytearraylist/qbytearraylist.pro b/src/corelib/doc/snippets/qbytearraylist/qbytearraylist.pro deleted file mode 100644 index 87397b491d..0000000000 --- a/src/corelib/doc/snippets/qbytearraylist/qbytearraylist.pro +++ /dev/null @@ -1,2 +0,0 @@ -QT = core -SOURCES = main.cpp diff --git a/src/corelib/doc/snippets/qdebug/qdebugsnippet.cpp b/src/corelib/doc/snippets/qdebug/qdebugsnippet.cpp index 90e7e618b5..33f6039995 100644 --- a/src/corelib/doc/snippets/qdebug/qdebugsnippet.cpp +++ b/src/corelib/doc/snippets/qdebug/qdebugsnippet.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> #include <QtDebug> diff --git a/src/corelib/doc/snippets/qdir-listfiles/main.cpp b/src/corelib/doc/snippets/qdir-listfiles/main.cpp index 58d512b08e..236b32c73d 100644 --- a/src/corelib/doc/snippets/qdir-listfiles/main.cpp +++ b/src/corelib/doc/snippets/qdir-listfiles/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] #include <QDir> diff --git a/src/corelib/doc/snippets/qdir-namefilters/main.cpp b/src/corelib/doc/snippets/qdir-namefilters/main.cpp index 500b32159e..b154c66310 100644 --- a/src/corelib/doc/snippets/qdir-namefilters/main.cpp +++ b/src/corelib/doc/snippets/qdir-namefilters/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QDir> #include <iostream> diff --git a/src/corelib/doc/snippets/qelapsedtimer/main.cpp b/src/corelib/doc/snippets/qelapsedtimer/main.cpp index 408c4eab07..b24e231a25 100644 --- a/src/corelib/doc/snippets/qelapsedtimer/main.cpp +++ b/src/corelib/doc/snippets/qelapsedtimer/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore> void slowOperation1() diff --git a/src/corelib/doc/snippets/qloggingcategory/main.cpp b/src/corelib/doc/snippets/qloggingcategory/main.cpp index f5c47b2ae8..8b3a61d51f 100644 --- a/src/corelib/doc/snippets/qloggingcategory/main.cpp +++ b/src/corelib/doc/snippets/qloggingcategory/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QCoreApplication> #include <QLoggingCategory> @@ -86,15 +39,20 @@ void myCategoryFilter(QLoggingCategory *); //![20] //![21] -QLoggingCategory::CategoryFilter oldCategoryFilter; +static QLoggingCategory::CategoryFilter oldCategoryFilter = nullptr; void myCategoryFilter(QLoggingCategory *category) { - // configure driver.usb category here, otherwise forward to to default filter. + // For a category set up after this filter is installed, we first set it up + // with the old filter. This ensures that any driver.usb logging configured + // by the user is kept, aside from the one level we override; and any new + // categories we're not interested in get configured by the old filter. + if (oldCategoryFilter) + oldCategoryFilter(category); + + // Tweak driver.usb's logging, over-riding the default filter: if (qstrcmp(category->categoryName(), "driver.usb") == 0) category->setEnabled(QtDebugMsg, true); - else - oldCategoryFilter(category); } //![21] @@ -107,8 +65,6 @@ int main(int argc, char *argv[]) //![2] //![22] - -// ... oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter); //![22] @@ -175,6 +131,20 @@ oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter); //![15] } + { +//![16] + QLoggingCategory category("driver.usb"); + qCFatal(category) << "a fatal message. Program will be terminated!"; +//![16] + } + + { +//![17] + QLoggingCategory category("driver.usb"); + qCFatal(category, "a fatal message. Program will be terminated!"); +//![17] + } + return 0; } diff --git a/src/corelib/doc/snippets/qmessageauthenticationcode/main.cpp b/src/corelib/doc/snippets/qmessageauthenticationcode/main.cpp index f93b407761..21c55568ca 100644 --- a/src/corelib/doc/snippets/qmessageauthenticationcode/main.cpp +++ b/src/corelib/doc/snippets/qmessageauthenticationcode/main.cpp @@ -1,52 +1,6 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Ruslan Nigmatullin <euroelessar@yandex.ru> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2016 Ruslan Nigmatullin <euroelessar@yandex.ru> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore> @@ -60,13 +14,12 @@ int main(int argc, char *argv[]) //! [0] //! [1] - QMessageAuthenticationCode code(QCryptographicHash::Sha1); - code.setKey(key); + QMessageAuthenticationCode code(QCryptographicHash::Sha256, key); code.addData(message); - code.result().toHex(); // returns "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" + code.result().toHex(); // returns "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8" //! [1] //! [2] - QMessageAuthenticationCode::hash(message, key, QCryptographicHash::Sha1).toHex(); + QMessageAuthenticationCode::hash(message, key, QCryptographicHash::Sha256).toHex(); //! [2] } diff --git a/src/corelib/doc/snippets/qmetaobject-invokable/main.cpp b/src/corelib/doc/snippets/qmetaobject-invokable/main.cpp index 28ef7981d1..c2ef624b7b 100644 --- a/src/corelib/doc/snippets/qmetaobject-invokable/main.cpp +++ b/src/corelib/doc/snippets/qmetaobject-invokable/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QDebug> diff --git a/src/corelib/doc/snippets/qmetaobject-invokable/qmetaobject-invokable.pro b/src/corelib/doc/snippets/qmetaobject-invokable/qmetaobject-invokable.pro deleted file mode 100644 index 4df19215f0..0000000000 --- a/src/corelib/doc/snippets/qmetaobject-invokable/qmetaobject-invokable.pro +++ /dev/null @@ -1,3 +0,0 @@ -HEADERS = window.h -SOURCES = main.cpp \ - window.cpp diff --git a/src/corelib/doc/snippets/qmetaobject-invokable/window.cpp b/src/corelib/doc/snippets/qmetaobject-invokable/window.cpp index 4061221857..f5ce70306d 100644 --- a/src/corelib/doc/snippets/qmetaobject-invokable/window.cpp +++ b/src/corelib/doc/snippets/qmetaobject-invokable/window.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include "window.h" diff --git a/src/corelib/doc/snippets/qmetaobject-invokable/window.h b/src/corelib/doc/snippets/qmetaobject-invokable/window.h index 1ffc6df6ae..13ab49a6af 100644 --- a/src/corelib/doc/snippets/qmetaobject-invokable/window.h +++ b/src/corelib/doc/snippets/qmetaobject-invokable/window.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #ifndef WINDOW_H #define WINDOW_H diff --git a/src/corelib/doc/snippets/qmetaobject-revision/main.cpp b/src/corelib/doc/snippets/qmetaobject-revision/main.cpp index 4854657911..8081f979d3 100644 --- a/src/corelib/doc/snippets/qmetaobject-revision/main.cpp +++ b/src/corelib/doc/snippets/qmetaobject-revision/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Research In Motion. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Research In Motion. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QMetaObject> diff --git a/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro b/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro deleted file mode 100644 index ec9d7db658..0000000000 --- a/src/corelib/doc/snippets/qmetaobject-revision/qmetaobject-revision.pro +++ /dev/null @@ -1,4 +0,0 @@ -QT += widgets -HEADERS = window.h -SOURCES = main.cpp \ - window.cpp diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.cpp b/src/corelib/doc/snippets/qmetaobject-revision/window.cpp index b8c13d83ec..77950a5656 100644 --- a/src/corelib/doc/snippets/qmetaobject-revision/window.cpp +++ b/src/corelib/doc/snippets/qmetaobject-revision/window.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Research In Motion. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Research In Motion. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include "window.h" diff --git a/src/corelib/doc/snippets/qmetaobject-revision/window.h b/src/corelib/doc/snippets/qmetaobject-revision/window.h index f519a6f2dc..d08780330f 100644 --- a/src/corelib/doc/snippets/qmetaobject-revision/window.h +++ b/src/corelib/doc/snippets/qmetaobject-revision/window.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 Research In Motion. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 Research In Motion. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #ifndef WINDOW_H #define WINDOW_H diff --git a/src/corelib/doc/snippets/qmetatype/registerConverters.cpp b/src/corelib/doc/snippets/qmetatype/registerConverters.cpp new file mode 100644 index 0000000000..f53d04b7a6 --- /dev/null +++ b/src/corelib/doc/snippets/qmetatype/registerConverters.cpp @@ -0,0 +1,62 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QJsonObject> +#include <QMetaType> +#include <QString> + +int main() { + //! [member] + struct Coordinates { + int x; + int y; + int z; + + QString toString() const { return u"[x: %1; y: %2, z: %3]"_s.arg(QString::number(x), + QString::number(y), + QString::number(z)); } + }; + QMetaType::registerConverter<Coordinates, QString>(&Coordinates::toString); + //! [member] + + //! [memberOk] + struct BigNumber { + long long l; + + int toInt(bool *ok = nullptr) const { + const bool canConvertSafely = l < std::numeric_limits<int>::max(); + if (ok) + *ok = canConvertSafely; + return l; + } + }; + QMetaType::registerConverter<BigNumber, int>(&BigNumber::toInt); + //! [memberOk] + + //! [implicit] + class Counter { + int number = 0; + public: + int value() const { return number; } + operator int() const { return value(); } + void increment() {++number;} + }; + QMetaType::registerConverter<Counter, int>(); + //! [implicit] + + struct CustomStringType { + const char *data() const {return nullptr;} + }; + //! [unaryfunc] + QMetaType::registerConverter<CustomStringType, QString>([](const CustomStringType &str) { + return QString::fromUtf8(str.data()); + }); + QMetaType::registerConverter<QJsonValue, QPointF>( + [](const QJsonValue &value) -> std::optional<QPointF> { + const auto object = value.toObject(); + if (!object.contains("x") || !object.contains("y")) + return std::nullopt; // The conversion fails if the required properties are missing + return QPointF{object["x"].toDouble(), object["y"].toDouble()}; + }); + //! [unaryfunc] +} diff --git a/src/corelib/doc/snippets/qprocess-environment/main.cpp b/src/corelib/doc/snippets/qprocess-environment/main.cpp index 8e967582ba..f443f0074e 100644 --- a/src/corelib/doc/snippets/qprocess-environment/main.cpp +++ b/src/corelib/doc/snippets/qprocess-environment/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore> diff --git a/src/corelib/doc/snippets/qprocess/qprocess-createprocessargumentsmodifier.cpp b/src/corelib/doc/snippets/qprocess/qprocess-createprocessargumentsmodifier.cpp index 4310864ff0..b084e99abd 100644 --- a/src/corelib/doc/snippets/qprocess/qprocess-createprocessargumentsmodifier.cpp +++ b/src/corelib/doc/snippets/qprocess/qprocess-createprocessargumentsmodifier.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QCoreApplication> #include <QProcess> diff --git a/src/corelib/doc/snippets/qprocess/qprocess-simpleexecution.cpp b/src/corelib/doc/snippets/qprocess/qprocess-simpleexecution.cpp index 6e9febe2e4..0715108754 100644 --- a/src/corelib/doc/snippets/qprocess/qprocess-simpleexecution.cpp +++ b/src/corelib/doc/snippets/qprocess/qprocess-simpleexecution.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QApplication> #include <QtGui> diff --git a/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp b/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp index 879cdbe329..e2e97fa11c 100644 --- a/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp +++ b/src/corelib/doc/snippets/qsignalmapper/buttonwidget.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include "buttonwidget.h" @@ -58,10 +11,10 @@ ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent) { signalMapper = new QSignalMapper(this); - QGridLayout *gridLayout = new QGridLayout; + 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); @@ -70,8 +23,6 @@ ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent) connect(signalMapper, &QSignalMapper::mappedString, //! [1] //! [2] this, &ButtonWidget::clicked); - - setLayout(gridLayout); } //! [2] @@ -79,13 +30,12 @@ ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent) ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent) : QWidget(parent) { - QGridLayout *gridLayout = new QGridLayout; + QGridLayout *gridLayout = new QGridLayout(this); for (int i = 0; i < texts.size(); ++i) { QString text = texts[i]; QPushButton *button = new QPushButton(text); connect(button, &QPushButton::clicked, [this, text] { clicked(text); }); gridLayout->addWidget(button, i / 3, i % 3); } - setLayout(gridLayout); } //! [3] diff --git a/src/corelib/doc/snippets/qsignalmapper/buttonwidget.h b/src/corelib/doc/snippets/qsignalmapper/buttonwidget.h index b9d59f8dd8..537c21c914 100644 --- a/src/corelib/doc/snippets/qsignalmapper/buttonwidget.h +++ b/src/corelib/doc/snippets/qsignalmapper/buttonwidget.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #ifndef BUTTONWIDGET_H #define BUTTONWIDGET_H @@ -55,7 +8,6 @@ class QSignalMapper; class QString; -class QStringList; //! [0] class ButtonWidget : public QWidget diff --git a/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp b/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp index 2a7b310716..962bece207 100644 --- a/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp +++ b/src/corelib/doc/snippets/qsortfilterproxymodel-details/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> #include <QApplication> @@ -55,7 +8,7 @@ class MyItemModel : public QStandardItemModel { public: - MyItemModel(QWidget *parent = 0); + MyItemModel(QWidget *parent = nullptr); }; MyItemModel::MyItemModel(QWidget *parent) @@ -65,7 +18,7 @@ MyItemModel::MyItemModel(QWidget *parent) class Widget : public QWidget { public: - Widget(QWidget *parent = 0); + Widget(QWidget *parent = nullptr); }; Widget::Widget(QWidget *parent) diff --git a/src/corelib/doc/snippets/qstack/main.cpp b/src/corelib/doc/snippets/qstack/main.cpp index 66823bcb59..f1f8e6a0fd 100644 --- a/src/corelib/doc/snippets/qstack/main.cpp +++ b/src/corelib/doc/snippets/qstack/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> #include <iostream> diff --git a/src/corelib/doc/snippets/qstring/main.cpp b/src/corelib/doc/snippets/qstring/main.cpp index 39c4a8045b..8b39ae2f13 100644 --- a/src/corelib/doc/snippets/qstring/main.cpp +++ b/src/corelib/doc/snippets/qstring/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> #include <QApplication> @@ -55,7 +8,7 @@ class Widget : public QWidget { public: - Widget(QWidget *parent = 0); + Widget(QWidget *parent = nullptr); void constCharPointer(); void constCharArray(); @@ -85,11 +38,10 @@ public: void isNullFunction(); void isEmptyFunction(); void lastIndexOfFunction(); - void leftFunction(); + void firstFunction(); void leftJustifiedFunction(); - void leftRefFunction(); - void midFunction(); - void midRefFunction(); + void slicedFunction(); + void sliceFunction(); void numberFunction(); void prependFunction(); @@ -97,9 +49,8 @@ public: void replaceFunction(); void reserveFunction(); void resizeFunction(); - void rightFunction(); + void lastFunction(); void rightJustifiedFunction(); - void rightRefFunction(); void sectionFunction(); void setNumFunction(); void simplifiedFunction(); @@ -167,7 +118,7 @@ void Widget::atFunction() //! [3] QString str; - for (int i = 0; i < str.size(); ++i) { + for (qsizetype i = 0; i < str.size(); ++i) { if (str.at(i) >= QChar('a') && str.at(i) <= QChar('f')) qDebug() << "Found character in range [a-f]"; } @@ -200,7 +151,7 @@ void Widget::index() { //! [6] QString str = "We must be <b>bold</b>, very <b>bold</b>"; - int j = 0; + qsizetype j = 0; while ((j = str.indexOf("<b>", j)) != -1) { qDebug() << "Found <b> tag at index position" << j; @@ -396,7 +347,7 @@ void Widget::fromRawDataFunction() static const QChar unicode[] = { 0x005A, 0x007F, 0x00A4, 0x0060, 0x1009, 0x0020, 0x0020}; - int size = sizeof(unicode) / sizeof(QChar); + qsizetype size = sizeof(unicode) / sizeof(QChar); QString str = QString::fromRawData(unicode, size); if (str.contains(pattern) { @@ -481,11 +432,11 @@ void Widget::lastIndexOfFunction() //! [94] } -void Widget::leftFunction() +void Widget::firstFunction() { //! [31] QString x = "Pineapple"; - QString y = x.left(4); // y == "Pine" + QString y = x.first(4); // y == "Pine" //! [31] } @@ -502,12 +453,12 @@ void Widget::leftJustifiedFunction() //! [33] } -void Widget::midFunction() +void Widget::slicedFunction() { //! [34] QString x = "Nine pineapples"; - QString y = x.mid(5, 4); // y == "pine" - QString z = x.mid(5); // z == "pineapples" + QString y = x.sliced(5, 4); // y == "pine" + QString z = x.sliced(5); // z == "pineapples" //! [34] } @@ -589,7 +540,7 @@ void Widget::reserveFunction() { //! [44] QString result; - int maxSize; + qsizetype maxSize; bool condition; QChar nextChar; @@ -626,11 +577,11 @@ void Widget::resizeFunction() //! [47] } -void Widget::rightFunction() +void Widget::lastFunction() { //! [48] QString x = "Pineapple"; - QString y = x.right(5); // y == "apple" + QString y = x.last(5); // y == "apple" //! [48] } @@ -703,7 +654,7 @@ void Widget::sizeFunction() { //! [58] QString str = "World"; - int n = str.size(); // n == 5 + qsizetype n = str.size(); // n == 5 str.data()[0]; // returns 'W' str.data()[4]; // returns 'd' //! [58] @@ -738,10 +689,10 @@ void Widget::splitCaseSensitiveFunction() //! [62] QString str = QStringLiteral("a,,b,c"); - QStringList list1 = str.split(QLatin1Char(',')); + QStringList list1 = str.split(u','); // list1: [ "a", "", "b", "c" ] - QStringList list2 = str.split(QLatin1Char(','), Qt::SkipEmptyParts); + QStringList list2 = str.split(u',', Qt::SkipEmptyParts); // list2: [ "a", "b", "c" ] //! [62] @@ -753,7 +704,7 @@ void Widget::splitCaseSensitiveFunction() //! [62-slashes] QString str = "/a/b/c/"; - auto parts = str.split(QLatin1Char('/')); + auto parts = str.split(u'/'); // parts: {"", "a", "b", "c", ""} //! [62-slashes] } @@ -959,29 +910,13 @@ void Widget::arrayOperator() //! [85] } -void Widget::midRefFunction() +void Widget::sliceFunction() { - //! [midRef] - QString x = "Nine pineapples"; - QStringRef y = x.midRef(5, 4); // y == "pine" - QStringRef z = x.midRef(5); // z == "pineapples" - //! [midRef] -} - -void Widget::leftRefFunction() -{ - //! [leftRef] - QString x = "Pineapple"; - QStringRef y = x.leftRef(4); // y == "Pine" - //! [leftRef] -} - -void Widget::rightRefFunction() -{ - //! [rightRef] - QString x = "Pineapple"; - QStringRef y = x.rightRef(5); // y == "apple" - //! [rightRef] + //! [86] + QString x = u"Nine pineapples"_s; + x.slice(5); // x == "pineapples" + x.slice(4, 3); // x == "app" + //! [86] } diff --git a/src/corelib/doc/snippets/qstring/stringbuilder.cpp b/src/corelib/doc/snippets/qstring/stringbuilder.cpp index ca89c3a232..c3a709bd4c 100644 --- a/src/corelib/doc/snippets/qstring/stringbuilder.cpp +++ b/src/corelib/doc/snippets/qstring/stringbuilder.cpp @@ -1,72 +1,46 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QString> + +using namespace Qt::StringLiterals; //! [0] QString foo; QString type = "long"; - foo->setText(QLatin1String("vector<") + type + QLatin1String(">::iterator")); + foo = "vector<"_L1 + type + ">::iterator"_L1; if (foo.startsWith("(" + type + ") 0x")) ... //! [0] -//! [3] - DEFINES *= QT_USE_QSTRINGBUILDER -//! [3] - //! [5] #include <QStringBuilder> QString hello("hello"); - QStringRef el(&hello, 2, 3); - QLatin1String world("world"); + QStringView el = QStringView{ hello }.mid(2, 3); + QLatin1StringView world("world"); QString message = hello % el % world % QChar('!'); //! [5] + +//! [6] + QString str("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<...> + auto concatenateStr = []() { + return "Like hot glue, " % str % " concatenates strings"; + }; +//! [6] + +//! [7] + QString s = "Like hot glue, " % str % " concatenates strings"; + + // With a lambda, specify a trailing return type: + auto concatenateStr = []() -> QString { + return "Like hot glue, " % str % " concatenates strings"; + }; +//! [7] diff --git a/src/corelib/doc/snippets/qstringlist/main.cpp b/src/corelib/doc/snippets/qstringlist/main.cpp index 5284a5fb78..1b7453cf6a 100644 --- a/src/corelib/doc/snippets/qstringlist/main.cpp +++ b/src/corelib/doc/snippets/qstringlist/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> #include <iostream> @@ -55,7 +8,7 @@ using namespace std; class Widget : public QWidget { public: - Widget(QWidget *parent = 0); + Widget(QWidget *parent = nullptr); }; Widget::Widget(QWidget *parent) @@ -69,24 +22,6 @@ Widget::Widget(QWidget *parent) fonts << "Courier" << "Verdana"; //! [0b] -//! [1] - for (int i = 0; i < fonts.size(); ++i) - cout << fonts.at(i).toLocal8Bit().constData() << Qt::endl; -//! [1] - -//! [2] - QStringListIterator javaStyleIterator(fonts); - while (javaStyleIterator.hasNext()) - cout << javaStyleIterator.next().toLocal8Bit().constData() << Qt::endl; -//! [2] - -//! [3] - QStringList::const_iterator constIterator; - for (constIterator = fonts.constBegin(); constIterator != fonts.constEnd(); - ++constIterator) - cout << (*constIterator).toLocal8Bit().constData() << Qt::endl; -//! [3] - //! [4] QString str = fonts.join(", "); // str == "Arial, Helvetica, Times, Courier" @@ -131,7 +66,7 @@ Widget::Widget(QWidget *parent) result.clear(); //! [12] - foreach (const QString &str, list) { + for (const auto &str : std::as_const(list)) { if (str.contains("Bill")) result += str; } @@ -158,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/qstringlistmodel/main.cpp b/src/corelib/doc/snippets/qstringlistmodel/main.cpp index 4c9519d2b2..b0d14e110e 100644 --- a/src/corelib/doc/snippets/qstringlistmodel/main.cpp +++ b/src/corelib/doc/snippets/qstringlistmodel/main.cpp @@ -1,59 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> class Widget : public QWidget { public: - Widget(QWidget *parent = 0); + Widget(QWidget *parent = nullptr); }; Widget::Widget(QWidget *parent) diff --git a/src/corelib/doc/snippets/qtcast/qtcast.cpp b/src/corelib/doc/snippets/qtcast/qtcast.cpp index ba8582eabb..177446aff9 100644 --- a/src/corelib/doc/snippets/qtcast/qtcast.cpp +++ b/src/corelib/doc/snippets/qtcast/qtcast.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QLabel> #include <QPushButton> diff --git a/src/corelib/doc/snippets/qversionnumber/main.cpp b/src/corelib/doc/snippets/qversionnumber/main.cpp index 27b7b1a7ef..b78e14edf1 100644 --- a/src/corelib/doc/snippets/qversionnumber/main.cpp +++ b/src/corelib/doc/snippets/qversionnumber/main.cpp @@ -1,53 +1,6 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Copyright (C) 2016 Keith Gardner <kreios4004@gmail.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// Copyright (C) 2016 Keith Gardner <kreios4004@gmail.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QVersionNumber> @@ -90,15 +43,15 @@ void QObject::parse() { //! [3] QString string("5.4.0-alpha"); - int suffixIndex; + qsizetype suffixIndex; QVersionNumber version = QVersionNumber::fromString(string, &suffixIndex); // version is 5.4.0 // suffixIndex is 5 //! [3] //! [3-latin1-1] - QLatin1String string("5.4.0-alpha"); - int suffixIndex; + QLatin1StringView string("5.4.0-alpha"); + qsizetype suffixIndex; auto version = QVersionNumber::fromString(string, &suffixIndex); // version is 5.4.0 // suffixIndex is 5 diff --git a/src/corelib/doc/snippets/qxmlstreamwriter/main.cpp b/src/corelib/doc/snippets/qxmlstreamwriter/main.cpp index 5a300499ba..ccf536c413 100644 --- a/src/corelib/doc/snippets/qxmlstreamwriter/main.cpp +++ b/src/corelib/doc/snippets/qxmlstreamwriter/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QCoreApplication> #include <QFile> diff --git a/src/corelib/doc/snippets/resource-system/CMakeLists.txt b/src/corelib/doc/snippets/resource-system/CMakeLists.txt new file mode 100644 index 0000000000..f0ec0f6816 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/CMakeLists.txt @@ -0,0 +1,41 @@ +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +project(my_app) +cmake_minimum_required(VERSION 3.16) +find_package(Qt6 REQUIRED COMPONENTS Widgets Qml) + +#! [AUTORCC] +set(CMAKE_AUTORCC ON) + +qt_add_executable(my_app + application.qrc + main.cpp +) +#! [AUTORCC] + +#! [qt_add_resources] +qt_add_resources(my_app "app_images" + PREFIX "/" + FILES + images/copy.png + images/cut.png + images/new.png + images/open.png + images/paste.png + images/save.png +) +#! [qt_add_resources] + +#! [qt_add_big_resources] +qt_add_big_resources(SOURCES application.qrc) +target_sources(my_app PRIVATE ${SOURCES}) +#! [qt_add_big_resources] + +#! [qt_add_binary_resources] +qt_add_binary_resources(resources application.qrc DESTINATION application.rcc) +add_dependencies(my_app resources) +#! [qt_add_binary_resources] + +target_link_libraries(my_app + PRIVATE Qt6::Qml Qt6::Widgets) diff --git a/src/corelib/doc/snippets/resource-system/application.pro b/src/corelib/doc/snippets/resource-system/application.pro index 0f451754f2..42c66eba4c 100644 --- a/src/corelib/doc/snippets/resource-system/application.pro +++ b/src/corelib/doc/snippets/resource-system/application.pro @@ -1,12 +1,26 @@ -QT += widgets - -HEADERS = mainwindow.h -SOURCES = main.cpp \ - mainwindow.cpp -#! [0] -RESOURCES = application.qrc -#! [0] - -# install -target.path = $$[QT_INSTALL_EXAMPLES]/widgets/mainwindows/application -INSTALLS += target +TEMPLATE = app + +QT += qml widgets + +#! [0] #! [qrc] +RESOURCES = application.qrc +#! [0] #! [qrc] + +#! [1] +resources.files = \ + images/copy.png \ + images/cut.png \ + images/new.png \ + images/open.png \ + images/paste.png \ + images/save.png +resources.prefix = / + +RESOURCES = resources +#! [1] + +#! [2] +CONFIG += resources_big +#! [2] + +SOURCES += main.cpp diff --git a/src/corelib/doc/snippets/resource-system/application.qrc b/src/corelib/doc/snippets/resource-system/application.qrc index 0a776fab4d..3eef379234 100644 --- a/src/corelib/doc/snippets/resource-system/application.qrc +++ b/src/corelib/doc/snippets/resource-system/application.qrc @@ -1,10 +1,10 @@ -<!DOCTYPE RCC><RCC version="1.0"> -<qresource> - <file>images/copy.png</file> - <file>images/cut.png</file> - <file>images/new.png</file> - <file>images/open.png</file> - <file>images/paste.png</file> - <file>images/save.png</file> -</qresource> +<RCC> + <qresource prefix="/"> + <file>images/copy.png</file> + <file>images/cut.png</file> + <file>images/new.png</file> + <file>images/open.png</file> + <file>images/paste.png</file> + <file>images/save.png</file> + </qresource> </RCC> diff --git a/src/corelib/doc/snippets/resource-system/images/copy.png b/src/corelib/doc/snippets/resource-system/images/copy.png Binary files differnew file mode 100644 index 0000000000..91a99b94e2 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/images/copy.png diff --git a/src/corelib/doc/snippets/resource-system/images/cut.png b/src/corelib/doc/snippets/resource-system/images/cut.png Binary files differnew file mode 100644 index 0000000000..91a99b94e2 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/images/cut.png diff --git a/src/corelib/doc/snippets/resource-system/images/new.png b/src/corelib/doc/snippets/resource-system/images/new.png Binary files differnew file mode 100644 index 0000000000..91a99b94e2 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/images/new.png diff --git a/src/corelib/doc/snippets/resource-system/images/open.png b/src/corelib/doc/snippets/resource-system/images/open.png Binary files differnew file mode 100644 index 0000000000..91a99b94e2 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/images/open.png diff --git a/src/corelib/doc/snippets/resource-system/images/paste.png b/src/corelib/doc/snippets/resource-system/images/paste.png Binary files differnew file mode 100644 index 0000000000..91a99b94e2 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/images/paste.png diff --git a/src/corelib/doc/snippets/resource-system/images/save.png b/src/corelib/doc/snippets/resource-system/images/save.png Binary files differnew file mode 100644 index 0000000000..91a99b94e2 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/images/save.png diff --git a/src/corelib/doc/snippets/resource-system/main.cpp b/src/corelib/doc/snippets/resource-system/main.cpp new file mode 100644 index 0000000000..7089ebf576 --- /dev/null +++ b/src/corelib/doc/snippets/resource-system/main.cpp @@ -0,0 +1,28 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QQmlApplicationEngine> +#include <QAction> +#include <QIcon> +#include <QApplication> +#include <QWidget> + +class DummyWidget : public QWidget { + Q_OBJECT + + QAction *cutAct; + + DummyWidget() { + //! [QAction] + cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this); + //! [QAction] + } +}; + +int main() +{ +//! [url] + QQmlApplicationEngine engine; + engine.load(QUrl("qrc:/myapp/main.qml")); +//! [url] +} diff --git a/src/corelib/doc/snippets/resource-system/mainwindow.cpp b/src/corelib/doc/snippets/resource-system/mainwindow.cpp index 6dc525304c..de98aa56ec 100644 --- a/src/corelib/doc/snippets/resource-system/mainwindow.cpp +++ b/src/corelib/doc/snippets/resource-system/mainwindow.cpp @@ -1,62 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [0] +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + #include <QtWidgets> #include "mainwindow.h" -//! [0] - -//! [1] MainWindow::MainWindow() -//! [1] //! [2] { textEdit = new QPlainTextEdit; setCentralWidget(textEdit); @@ -74,11 +22,8 @@ MainWindow::MainWindow() setCurrentFile(QString()); setUnifiedTitleAndToolBarOnMac(true); } -//! [2] -//! [3] void MainWindow::closeEvent(QCloseEvent *event) -//! [3] //! [4] { if (maybeSave()) { writeSettings(); @@ -87,22 +32,16 @@ void MainWindow::closeEvent(QCloseEvent *event) event->ignore(); } } -//! [4] -//! [5] void MainWindow::newFile() -//! [5] //! [6] { if (maybeSave()) { textEdit->clear(); setCurrentFile(QString()); } } -//! [6] -//! [7] void MainWindow::open() -//! [7] //! [8] { if (maybeSave()) { QString fileName = QFileDialog::getOpenFileName(this); @@ -110,11 +49,8 @@ void MainWindow::open() loadFile(fileName); } } -//! [8] -//! [9] bool MainWindow::save() -//! [9] //! [10] { if (curFile.isEmpty()) { return saveAs(); @@ -122,11 +58,8 @@ bool MainWindow::save() return saveFile(curFile); } } -//! [10] -//! [11] bool MainWindow::saveAs() -//! [11] //! [12] { QString fileName = QFileDialog::getSaveFileName(this); if (fileName.isEmpty()) @@ -134,42 +67,31 @@ bool MainWindow::saveAs() return saveFile(fileName); } -//! [12] -//! [13] void MainWindow::about() -//! [13] //! [14] { QMessageBox::about(this, tr("About Application"), tr("The <b>Application</b> example demonstrates how to " "write modern GUI applications using Qt, with a menu bar, " "toolbars, and a status bar.")); } -//! [14] -//! [15] void MainWindow::documentWasModified() -//! [15] //! [16] { setWindowModified(textEdit->document()->isModified()); } -//! [16] -//! [17] void MainWindow::createActions() -//! [17] //! [18] { newAct = new QAction(QIcon(":/images/new.png"), tr("&New"), this); newAct->setShortcuts(QKeySequence::New); newAct->setStatusTip(tr("Create a new file")); connect(newAct, &QAction::triggered, this, &MainWindow::newFile); -//! [19] openAct = new QAction(QIcon(":/images/open.png"), tr("&Open..."), this); openAct->setShortcuts(QKeySequence::Open); openAct->setStatusTip(tr("Open an existing file")); connect(openAct, &QAction::triggered, this, &MainWindow::open); -//! [18] //! [19] saveAct = new QAction(QIcon(":/images/save.png"), tr("&Save"), this); saveAct->setShortcuts(QKeySequence::Save); @@ -181,10 +103,8 @@ void MainWindow::createActions() saveAsAct->setStatusTip(tr("Save the document under a new name")); connect(saveAsAct, &QAction::triggered, this, &MainWindow::saveAs); -//! [20] exitAct = new QAction(tr("E&xit"), this); exitAct->setShortcuts(QKeySequence::Quit); -//! [20] exitAct->setStatusTip(tr("Exit the application")); connect(exitAct, &QAction::triggered, this, &MainWindow::close); @@ -212,34 +132,24 @@ void MainWindow::createActions() aboutAct->setStatusTip(tr("Show the application's About box")); connect(aboutAct, &QAction::triggered, this, &MainWindow::about); -//! [22] aboutQtAct = new QAction(tr("About &Qt"), this); aboutQtAct->setStatusTip(tr("Show the Qt library's About box")); connect(aboutQtAct, &QAction::triggered, qApp, &QApplication::aboutQt); -//! [22] -//! [23] cutAct->setEnabled(false); -//! [23] //! [24] copyAct->setEnabled(false); connect(textEdit, &QTextEdit::copyAvailable, cutAct, &QAction::setEnabled); connect(textEdit, &QTextEdit::copyAvailable, copyAct, &QAction::setEnabled); } -//! [24] -//! [25] //! [26] void MainWindow::createMenus() -//! [25] //! [27] { fileMenu = menuBar()->addMenu(tr("&File")); fileMenu->addAction(newAct); -//! [28] fileMenu->addAction(openAct); -//! [28] fileMenu->addAction(saveAct); -//! [26] fileMenu->addAction(saveAsAct); fileMenu->addSeparator(); fileMenu->addAction(exitAct); @@ -255,16 +165,12 @@ void MainWindow::createMenus() helpMenu->addAction(aboutAct); helpMenu->addAction(aboutQtAct); } -//! [27] -//! [29] //! [30] void MainWindow::createToolBars() { fileToolBar = addToolBar(tr("File")); fileToolBar->addAction(newAct); -//! [29] //! [31] fileToolBar->addAction(openAct); -//! [31] fileToolBar->addAction(saveAct); editToolBar = addToolBar(tr("Edit")); @@ -272,19 +178,13 @@ void MainWindow::createToolBars() editToolBar->addAction(copyAct); editToolBar->addAction(pasteAct); } -//! [30] -//! [32] void MainWindow::createStatusBar() -//! [32] //! [33] { statusBar()->showMessage(tr("Ready")); } -//! [33] -//! [34] //! [35] void MainWindow::readSettings() -//! [34] //! [36] { QSettings settings("QtProject", "Application Example"); QPoint pos = settings.value("pos", QPoint(200, 200)).toPoint(); @@ -292,21 +192,15 @@ void MainWindow::readSettings() resize(size); move(pos); } -//! [35] //! [36] -//! [37] //! [38] void MainWindow::writeSettings() -//! [37] //! [39] { QSettings settings("QtProject", "Application Example"); settings.setValue("pos", pos()); settings.setValue("size", size()); } -//! [38] //! [39] -//! [40] bool MainWindow::maybeSave() -//! [40] //! [41] { if (textEdit->document()->isModified()) { QMessageBox::StandardButton ret; @@ -321,11 +215,8 @@ bool MainWindow::maybeSave() } return true; } -//! [41] -//! [42] void MainWindow::loadFile(const QString &fileName) -//! [42] //! [43] { QFile file(fileName); if (!file.open(QFile::ReadOnly | QFile::Text)) { @@ -348,11 +239,8 @@ void MainWindow::loadFile(const QString &fileName) setCurrentFile(fileName); statusBar()->showMessage(tr("File loaded"), 2000); } -//! [43] -//! [44] bool MainWindow::saveFile(const QString &fileName) -//! [44] //! [45] { QFile file(fileName); if (!file.open(QFile::WriteOnly | QFile::Text)) { @@ -376,11 +264,8 @@ bool MainWindow::saveFile(const QString &fileName) statusBar()->showMessage(tr("File saved"), 2000); return true; } -//! [45] -//! [46] void MainWindow::setCurrentFile(const QString &fileName) -//! [46] //! [47] { curFile = fileName; textEdit->document()->setModified(false); @@ -391,12 +276,8 @@ void MainWindow::setCurrentFile(const QString &fileName) shownName = "untitled.txt"; setWindowFilePath(shownName); } -//! [47] -//! [48] QString MainWindow::strippedName(const QString &fullFileName) -//! [48] //! [49] { return QFileInfo(fullFileName).fileName(); } -//! [49] diff --git a/src/corelib/doc/snippets/settings/settings.cpp b/src/corelib/doc/snippets/settings/settings.cpp index 49312b9cfc..c73b42b2a4 100644 --- a/src/corelib/doc/snippets/settings/settings.cpp +++ b/src/corelib/doc/snippets/settings/settings.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtGui> @@ -152,8 +105,7 @@ void MainWindow::writeSettings() QSettings settings("Moose Soft", "Clipper"); settings.beginGroup("MainWindow"); - settings.setValue("size", size()); - settings.setValue("pos", pos()); + settings.setValue("geometry", saveGeometry()); settings.endGroup(); } //! [16] @@ -164,8 +116,11 @@ void MainWindow::readSettings() QSettings settings("Moose Soft", "Clipper"); settings.beginGroup("MainWindow"); - resize(settings.value("size", QSize(400, 400)).toSize()); - move(settings.value("pos", QPoint(200, 200)).toPoint()); + const auto geometry = settings.value("geometry", QByteArray()).toByteArray(); + if (geometry.isEmpty()) + setGeometry(200, 200, 400, 400); + else + restoreGeometry(geometry) settings.endGroup(); } //! [17] diff --git a/src/corelib/doc/snippets/sharedemployee/employee.h b/src/corelib/doc/snippets/sharedemployee/employee.h index 3b8e7133b7..c44f71499e 100644 --- a/src/corelib/doc/snippets/sharedemployee/employee.h +++ b/src/corelib/doc/snippets/sharedemployee/employee.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #ifndef EMPLOYEE_H #define EMPLOYEE_H diff --git a/src/corelib/doc/snippets/sharedemployee/main.cpp b/src/corelib/doc/snippets/sharedemployee/main.cpp index d1f51425b7..f3684e38a8 100644 --- a/src/corelib/doc/snippets/sharedemployee/main.cpp +++ b/src/corelib/doc/snippets/sharedemployee/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] #include "employee.h" diff --git a/src/corelib/doc/snippets/signalsandslots/lcdnumber.h b/src/corelib/doc/snippets/signalsandslots/lcdnumber.h index b311586e8f..f80b2186a8 100644 --- a/src/corelib/doc/snippets/signalsandslots/lcdnumber.h +++ b/src/corelib/doc/snippets/signalsandslots/lcdnumber.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] #ifndef LCDNUMBER_H diff --git a/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp b/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp index 31ed6ed08a..fe38a3222a 100644 --- a/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp +++ b/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include "signalsandslots.h" diff --git a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h index 760bc2c7b1..2f5a53231c 100644 --- a/src/corelib/doc/snippets/signalsandslots/signalsandslots.h +++ b/src/corelib/doc/snippets/signalsandslots/signalsandslots.h @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #ifndef SIGNALSANDSLOTS_H #define SIGNALSANDSLOTS_H diff --git a/src/corelib/doc/snippets/statemachine/eventtest.cpp b/src/corelib/doc/snippets/statemachine/eventtest.cpp deleted file mode 100644 index d7d4ce0d21..0000000000 --- a/src/corelib/doc/snippets/statemachine/eventtest.cpp +++ /dev/null @@ -1,83 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtGui> - -class MyTransition : public QAbstractTransition -{ - Q_OBJECT -public: - MyTransition() {} - -protected: -//![0] - bool eventTest(QEvent *event) override - { - if (event->type() == QEvent::Wrapped) { - QEvent *wrappedEvent = static_cast<QStateMachine::WrappedEvent *>(event)->event(); - if (wrappedEvent->type() == QEvent::KeyPress) { - QKeyEvent *keyEvent = static_cast<QKeyEvent *>(wrappedEvent); - // Do your event test - } - } - return false; - } -//![0] - - void onTransition(QEvent *event) override - { - - } -}; - -int main(int argv, char **args) -{ - return 0; -} diff --git a/src/corelib/doc/snippets/statemachine/main.cpp b/src/corelib/doc/snippets/statemachine/main.cpp deleted file mode 100644 index c399f4f199..0000000000 --- a/src/corelib/doc/snippets/statemachine/main.cpp +++ /dev/null @@ -1,98 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtWidgets> - -int main(int argv, char **args) -{ - QApplication app(argv, args); - - QLabel *label = new QLabel; - QPushButton *button = new QPushButton; - -//![0] - QStateMachine machine; - QState *s1 = new QState(); - QState *s2 = new QState(); - QState *s3 = new QState(); -//![0] - -//![4] - s1->assignProperty(label, "text", "In state s1"); - s2->assignProperty(label, "text", "In state s2"); - s3->assignProperty(label, "text", "In state s3"); -//![4] - -//![5] - QObject::connect(s3, &QState::entered, button, &QPushButton:showMaximized); - QObject::connect(s3, &QState::exited, button, &QPushButton::showMinimized); -//![5] - -//![1] - s1->addTransition(button, &QPushButton::clicked, s2); - s2->addTransition(button, &QPushButton::clicked, s3); - s3->addTransition(button, &QPushButton::clicked, s1); -//![1] - -//![2] - machine.addState(s1); - machine.addState(s2); - machine.addState(s3); - machine.setInitialState(s1); -//![2] - -//![3] - machine.start(); -//![3] - - label->show(); - - return app.exec(); -} diff --git a/src/corelib/doc/snippets/statemachine/main2.cpp b/src/corelib/doc/snippets/statemachine/main2.cpp deleted file mode 100644 index dedd2d29bf..0000000000 --- a/src/corelib/doc/snippets/statemachine/main2.cpp +++ /dev/null @@ -1,103 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtWidgets> - -int main(int argv, char **args) -{ - QApplication app(argv, args); - - QStateMachine machine; - -//![0] - QState *s1 = new QState(); - QState *s11 = new QState(s1); - QState *s12 = new QState(s1); - QState *s13 = new QState(s1); - s1->setInitialState(s11); - machine.addState(s1); -//![0] - -//![2] - s12->addTransition(quitButton, &QPushButton::clicked, s12); -//![2] - -//![1] - QFinalState *s2 = new QFinalState(); - s1->addTransition(quitButton, &QPushButton::clicked, s2); - machine.addState(s2); - machine.setInitialState(s1); - - QObject::connect(&machine, &QStateMachine::finished, - QCoreApplication::instance(), &QCoreApplication::quit); -//![1] - - QButton *interruptButton = new QPushButton("Interrupt Button"); - QWidget *mainWindow = new QWidget(); - -//![3] - QHistoryState *s1h = new QHistoryState(s1); - - QState *s3 = new QState(); - s3->assignProperty(label, "text", "In s3"); - QMessageBox *mbox = new QMessageBox(mainWindow); - mbox->addButton(QMessageBox::Ok); - mbox->setText("Interrupted!"); - mbox->setIcon(QMessageBox::Information); - QObject::connect(s3, &QState::entered, mbox, &QMessageBox::exec); - s3->addTransition(s1h); - machine.addState(s3); - - s1->addTransition(interruptButton, &QPushButton::clicked, s3); -//![3] - - return app.exec(); -} - diff --git a/src/corelib/doc/snippets/statemachine/main3.cpp b/src/corelib/doc/snippets/statemachine/main3.cpp deleted file mode 100644 index b665565aef..0000000000 --- a/src/corelib/doc/snippets/statemachine/main3.cpp +++ /dev/null @@ -1,70 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtGui> - -int main(int argv, char **args) -{ - QApplication app(argv, args); - -//![0] - QState *s1 = new QState(QState::ParallelStates); - // s11 and s12 will be entered in parallel - QState *s11 = new QState(s1); - QState *s12 = new QState(s1); -//![0] - -//![1] - s1->addTransition(s1, &QState::finished, s2); -//![1] - - return app.exec(); -} - diff --git a/src/corelib/doc/snippets/statemachine/main4.cpp b/src/corelib/doc/snippets/statemachine/main4.cpp deleted file mode 100644 index e21656b91c..0000000000 --- a/src/corelib/doc/snippets/statemachine/main4.cpp +++ /dev/null @@ -1,122 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtGui> - - -//![0] -struct StringEvent : public QEvent -{ - StringEvent(const QString &val) - : QEvent(QEvent::Type(QEvent::User+1)), - value(val) {} - - QString value; -}; -//![0] - -//![1] -class StringTransition : public QAbstractTransition -{ - Q_OBJECT - -public: - StringTransition(const QString &value) - : m_value(value) {} - -protected: - bool eventTest(QEvent *e) override - { - if (e->type() != QEvent::Type(QEvent::User+1)) // StringEvent - return false; - StringEvent *se = static_cast<StringEvent*>(e); - return (m_value == se->value); - } - - void onTransition(QEvent *) override {} - -private: - QString m_value; -}; -//![1] - -int main(int argv, char **args) -{ - QApplication app(argv, args); - -//![2] - QStateMachine machine; - QState *s1 = new QState(); - QState *s2 = new QState(); - QFinalState *done = new QFinalState(); - - StringTransition *t1 = new StringTransition("Hello"); - t1->setTargetState(s2); - s1->addTransition(t1); - StringTransition *t2 = new StringTransition("world"); - t2->setTargetState(done); - s2->addTransition(t2); - - machine.addState(s1); - machine.addState(s2); - machine.addState(done); - machine.setInitialState(s1); -//![2] - -//![3] - machine.postEvent(new StringEvent("Hello")); - machine.postEvent(new StringEvent("world")); -//![3] - - return app.exec(); -} - -#include "main4.moc" - diff --git a/src/corelib/doc/snippets/statemachine/main5.cpp b/src/corelib/doc/snippets/statemachine/main5.cpp deleted file mode 100644 index d701f51e2b..0000000000 --- a/src/corelib/doc/snippets/statemachine/main5.cpp +++ /dev/null @@ -1,182 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtGui> - -int main(int argv, char **args) -{ - QApplication app(argv, args); - QWidget *button; - - { -//![0] - QStateMachine machine; - machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); - - QState *s1 = new QState(); - s1->assignProperty(object, "fooBar", 1.0); - machine.addState(s1); - machine.setInitialState(s1); - - QState *s2 = new QState(); - machine.addState(s2); -//![0] - } - - { - -//![2] - QStateMachine machine; - machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); - - QState *s1 = new QState(); - s1->assignProperty(object, "fooBar", 1.0); - machine.addState(s1); - machine.setInitialState(s1); - - QState *s2 = new QState(s1); - s2->assignProperty(object, "fooBar", 2.0); - s1->setInitialState(s2); - - QState *s3 = new QState(s1); -//![2] - - } - - { -//![3] - QState *s1 = new QState(); - QState *s2 = new QState(); - - s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); - s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100)); - - s1->addTransition(button, &QPushButton::clicked, s2); -//![3] - - } - - { -//![4] - QState *s1 = new QState(); - QState *s2 = new QState(); - - s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); - s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100)); - - QSignalTransition *transition = s1->addTransition(button, &QPushButton::clicked, s2); - transition->addAnimation(new QPropertyAnimation(button, "geometry")); -//![4] - - } - - { - QMainWindow *mainWindow = 0; - -//![5] - QMessageBox *messageBox = new QMessageBox(mainWindow); - messageBox->addButton(QMessageBox::Ok); - messageBox->setText("Button geometry has been set!"); - messageBox->setIcon(QMessageBox::Information); - - QState *s1 = new QState(); - - QState *s2 = new QState(); - s2->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); - connect(s2, &QState::entered, messageBox, SLOT(exec())); - - s1->addTransition(button, &QPushButton::clicked, s2); -//![5] - } - - { - QMainWindow *mainWindow = 0; - -//![6] - QMessageBox *messageBox = new QMessageBox(mainWindow); - messageBox->addButton(QMessageBox::Ok); - messageBox->setText("Button geometry has been set!"); - messageBox->setIcon(QMessageBox::Information); - - QState *s1 = new QState(); - - QState *s2 = new QState(); - s2->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); - - QState *s3 = new QState(); - connect(s3, &QState::entered, messageBox, SLOT(exec())); - - s1->addTransition(button, &QPushButton::clicked, s2); - s2->addTransition(s2, &QState::propertiesAssigned, s3); -//![6] - - } - - { - -//![7] - QState *s1 = new QState(); - QState *s2 = new QState(); - - s2->assignProperty(object, "fooBar", 2.0); - s1->addTransition(s2); - - QStateMachine machine; - machine.setInitialState(s1); - machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar")); -//![7] - - } - - - - return app.exec(); -} - diff --git a/src/corelib/doc/snippets/streaming/main.cpp b/src/corelib/doc/snippets/streaming/main.cpp index 0c857b0528..a4f73526c5 100644 --- a/src/corelib/doc/snippets/streaming/main.cpp +++ b/src/corelib/doc/snippets/streaming/main.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore> #include <QByteArray> diff --git a/src/corelib/doc/snippets/streaming/streaming.pro b/src/corelib/doc/snippets/streaming/streaming.pro deleted file mode 100644 index 8c5eb91f05..0000000000 --- a/src/corelib/doc/snippets/streaming/streaming.pro +++ /dev/null @@ -1,2 +0,0 @@ -SOURCES = main.cpp -CONFIG += CONSOLE
\ No newline at end of file diff --git a/src/corelib/doc/snippets/threads/threads.cpp b/src/corelib/doc/snippets/threads/threads.cpp index a748755a19..502bc4bfe0 100644 --- a/src/corelib/doc/snippets/threads/threads.cpp +++ b/src/corelib/doc/snippets/threads/threads.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QCache> #include <QMutex> @@ -54,9 +7,7 @@ #define Counter ReentrantCounter -//! [3] class Counter -//! [3] //! [4] { public: Counter() { n = 0; } @@ -68,14 +19,11 @@ public: private: int n; }; -//! [4] #undef Counter #define Counter ThreadSafeCounter -//! [5] class Counter -//! [5] //! [6] { public: Counter() { n = 0; } @@ -88,7 +36,6 @@ private: mutable QMutex mutex; int n; }; -//! [6] typedef int SomeClass; diff --git a/src/corelib/doc/snippets/timers/analogclock.cpp b/src/corelib/doc/snippets/timers/analogclock.cpp index 3edfce3235..5241e57879 100644 --- a/src/corelib/doc/snippets/timers/analogclock.cpp +++ b/src/corelib/doc/snippets/timers/analogclock.cpp @@ -1,58 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtWidgets> #include "analogclock.h" -//! [0] //! [1] +// QTimer +//! [0] AnalogClock::AnalogClock(QWidget *parent) //! [0] //! [2] : QWidget(parent) @@ -70,11 +24,24 @@ AnalogClock::AnalogClock(QWidget *parent) resize(200, 200); //! [7] } -//! [1] //! [7] +//! [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] -//! [8] //! [9] void AnalogClock::paintEvent(QPaintEvent *) -//! [8] //! [10] { static const QPoint hourHand[3] = { QPoint(7, 8), @@ -92,64 +59,40 @@ void AnalogClock::paintEvent(QPaintEvent *) int side = qMin(width(), height()); QTime time = QTime::currentTime(); -//! [10] -//! [11] QPainter painter(this); -//! [11] //! [12] painter.setRenderHint(QPainter::Antialiasing); -//! [12] //! [13] painter.translate(width() / 2, height() / 2); -//! [13] //! [14] painter.scale(side / 200.0, side / 200.0); -//! [9] //! [14] -//! [15] painter.setPen(Qt::NoPen); -//! [15] //! [16] painter.setBrush(hourColor); -//! [16] -//! [17] //! [18] painter.save(); -//! [17] //! [19] painter.rotate(30.0 * ((time.hour() + time.minute() / 60.0))); painter.drawConvexPolygon(hourHand, 3); painter.restore(); -//! [18] //! [19] -//! [20] painter.setPen(hourColor); -//! [20] //! [21] for (int i = 0; i < 12; ++i) { painter.drawLine(88, 0, 96, 0); painter.rotate(30.0); } -//! [21] -//! [22] painter.setPen(Qt::NoPen); -//! [22] //! [23] painter.setBrush(minuteColor); -//! [24] painter.save(); painter.rotate(6.0 * (time.minute() + time.second() / 60.0)); painter.drawConvexPolygon(minuteHand, 3); painter.restore(); -//! [23] //! [24] -//! [25] painter.setPen(minuteColor); -//! [25] //! [26] -//! [27] for (int j = 0; j < 60; ++j) { if ((j % 5) != 0) painter.drawLine(92, 0, 96, 0); painter.rotate(6.0); } -//! [27] } -//! [26] diff --git a/src/corelib/doc/snippets/timers/timers.cpp b/src/corelib/doc/snippets/timers/timers.cpp index eb0c82c625..1a97ba535e 100644 --- a/src/corelib/doc/snippets/timers/timers.cpp +++ b/src/corelib/doc/snippets/timers/timers.cpp @@ -1,55 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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: @@ -82,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 9cbe50d4a9..3d6c1eefa2 100644 --- a/src/corelib/doc/src/animation.qdoc +++ b/src/corelib/doc/src/animation.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group animation @@ -46,162 +22,134 @@ \keyword Animation - The animation framework aims to provide an easy way for creating animated - and smooth GUIs. By animating Qt properties, the framework provides great - freedom for animating widgets and other \l{QObject}s. The framework can - also be used with the Graphics View framework. Many of the concepts - available in the animation framework are also available in \l{Qt Quick}, - where it offers a declarative way of defining animations. Much of the - knowledge acquired about the animation framework can be applied to - \l{Qt Quick}. + The animation framework provides an easy way to animate your GUI elements. + It enables you to animate a Qt property value of a widget or QObject. + Most of the features offered by the framework are also available in + \l{Qt Quick}, where it's possible to define animations in a declarative way. - In this overview, we explain the basics of its architecture. We - also show examples of the most common techniques that the - framework allows for animating \l{QObject}s and graphics items. + This overview explains the framework's architecture, with examples that + demonstrate the common techniques used for animating QObject and + GUI elements. \tableofcontents - \section1 The Animation Architecture + \section1 The Animation architecture - We will in this section take a high-level look at the animation - framework's architecture and how it is used to animate Qt - properties. The following diagram shows the most important classes - in the animation framework. + The following diagram shows the most important classes provided by the + framework: \image animations-architecture.png - The animation framework foundation consists of the base class - QAbstractAnimation, and its two subclasses QVariantAnimation and - QAnimationGroup. QAbstractAnimation is the ancestor of all - animations. It represents basic properties that are common for all - animations in the framework; notably, the ability to start, stop, - and pause an animation. It is also receives the time change - notifications. - - The animation framework further provides the QPropertyAnimation - class, which inherits QVariantAnimation and performs animation of - a Qt property, which is part of Qt's \l{Meta-Object - System}{meta-object system}. The class performs an interpolation - over the property using an easing curve. So when you want to - animate a value, you can declare it as a property and make your - class a QObject. Note that this gives us great freedom in - animating already existing widgets and other \l{QObject}s. + It includes the QAbstractAnimation class, which provides the + necessary foundation for animations. This class defines the + generic properties for all animations supported by the framework. + For example, the ability to start, stop, and pause an animation. The + class also receives the time change notifications. + + The framework further provides the QVariantAnimation and + QAnimationGroup classes, which build on their base case, QAbstractAnimation. + Next in the hierarchy is QPropertyAnimation, which is derived from + QVariantAnmiation, and it lets you animate a Qt property of a widget or + QObject. The class performs interpolation on the property value using an + easing curve. With these in place, you just need a QObject class with a + Qt property value that you can animate. + + \note It is required that the target object you are animating is a QObject + or its subclass. This is necessary as the animation framework depends on the + \l{Meta-Object System}{meta-object system} for all the information about the + object it is animating. Complex animations can be constructed by building a tree structure - of \l{QAbstractAnimation}s. The tree is built by using - \l{QAnimationGroup}s, which function as containers for other - animations. Note also that the groups are subclasses of - QAbstractAnimation, so groups can themselves contain other groups. + of \l{QAbstractAnimation}s, where the tree is a QAnimationGroup that + contains other animations. These animation groups can also contain + subgroups representing different groups or animations, such as + QParallelAnimationGroup and QSequentialAnimationGroup. - The animation framework can be used on its own, but is also - designed to be part of the state machine framework (See the - \l{The State Machine Framework}{state machine framework} for an - introduction to the Qt state machine). The state machine provides - a special state that can play an animation. A QState can also set - properties when the state is entered or exited, and this special - animation state will interpolate between these values when given a - QPropertyAnimation. We will look more closely at this later. + Behind the scenes, all animations are controlled by a global + timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} about + all animations that are running. - Behind the scenes, the animations are controlled by a global - timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to - all animations that are playing. + For detailed information of these individual classes' and their roles in + the framework, refer to their documentation. - For detailed descriptions of the classes' function and roles in - the framework, please look up their class descriptions. + \section1 Classes offered by the framework - \section1 Classes in the Animation Framework - - These classes provide a framework for creating both simple and complex - animations. + These classes provide the necessary infrastructure to create both simple and + complex animations. \annotatedlist animation - \section1 Animating Qt Properties + \section1 Animating Qt properties - As mentioned in the previous section, the QPropertyAnimation class can - interpolate over Qt properties. It is often this class that should be used - for animation of values; in fact, its superclass, QVariantAnimation, has an - empty implementation of \l{QVariantAnimation::}{updateCurrentValue()}, and - does not change any value unless we change it ourselves on the + As the QPropertyAnimation class can interpolate on Qt properties, it is + used often. In fact, its superclass---QVariantAnimation---provides an + abstract implementation of \l{QVariantAnimation::}{updateCurrentValue()}, + which does not change any value unless you change it on the \l{QVariantAnimation::valueChanged()}{valueChanged signal}. - A major reason we chose to animate Qt properties is that it - presents us with freedom to animate already existing classes in - the Qt API. Notably, the QWidget class (which we can also embed in - a QGraphicsView) has properties for its bounds, colors, etc. - Let's look at a small example: - - \code - QPushButton button("Animated Button"); - button.show(); + The framework lets you animate the Qt properties of the existing + classes in Qt. For example, the QWidget class---can be embedded in + a QGraphicsView---has properties for its bounds, colors, and so on. + The following example demonstrates how you can animate a QPushButton + widget: - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); - - animation.start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 - This code will move \c button from the top left corner of the - screen to the position (250, 250) in 10 seconds (10000 milliseconds). + The example animates the \c pos Qt property of a QPushButton, to move + it from the top--left corner of the screen to the end position (250, 250), + in 10 seconds (10000 milliseconds). - The example above will do a linear interpolation between the - start and end value. It is also possible to set values - situated between the start and end value. The interpolation - will then go by these points. + It uses the linear interpolation method to control the speed of + animation between the start and end values. Try adding another value + in--between the start and end value to see how they are interpolated. + This time use the QPropertyAnimation::setKeyValueAt function to add + these values: \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - - animation.setKeyValueAt(0, QRect(0, 0, 100, 30)); - animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30)); - animation.setKeyValueAt(1, QRect(0, 0, 100, 30)); - - animation.start(); + ... + anim->setDuration(10000); + anim->setKeyValueAt(0, QPoint(0, 0)); + anim->setKeyValueAt(0.8, QPoint(250, 250)); + anim->setKeyValueAt(1, QPoint(0, 0)); + ... \endcode - In this example, the animation will take the button to (250, 250) - in 8 seconds, and then move it back to its original position in - the remaining 2 seconds. The movement will be linearly - interpolated between these points. + In this example, the animation moves the button to + (250, 250) in 8 seconds, and moves it back to its original position in + the remaining 2 seconds. The button's movement is linear-interpolated + between these points. - You also have the possibility to animate values of a QObject - that is not declared as a Qt property. The only requirement is - that this value has a setter. You can then subclass the class - containing the value and declare a property that uses this setter. - Note that each Qt property requires a getter, so you will need to - provide a getter yourself if this is not defined. + You can also animate a QObject's value that is not declared as a Qt + property, if the value has a setter method. In such cases, derive + a new class from the class that contains the value, and add a Qt property + for that value with the setter. + + \note Each Qt property requires a getter also, so you should provide a + getter if that is not defined. \code class MyGraphicsRectItem : public QObject, public QGraphicsRectItem { Q_OBJECT - Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry) + Q_PROPERTY(QPointF pos READ pos WRITE setPos) }; \endcode - In the above code example, we subclass QGraphicsRectItem and - define a geometry property. We can now animate the widgets - geometry even if QGraphicsRectItem does not provide the geometry - property. + In this example, the \c MyGraphicsRectItem derives from + QGraphicsRectItem and QObject, and defines the \c pos property. You can + animate the item's \c pos even if QGraphicsRectItem does not provide + the \c pos property. - For a general introduction to the Qt property system, see its - \l{Qt's Property System}{overview}. + For a general introduction to the Qt property system, refer to + \l{Qt's Property System}. \section1 Animations and the Graphics View Framework - When you want to animate \l{QGraphicsItem}s, you also use - QPropertyAnimation. However, QGraphicsItem does not inherit QObject. - A good solution is to subclass the graphics item you wish to animate. - This class will then also inherit QObject. - This way, QPropertyAnimation can be used for \l{QGraphicsItem}s. - The example below shows how this is done. Another possibility is - to inherit QGraphicsWidget, which already is a QObject. + QPropertyAnimation can also be used to animate a QGraphicsItem, which does + not inherit QObject. In such cases, you derive a class from the graphics + item that you want to animate. This derived class should also inherit form + QObject to enable using QPropertyAnimation on a QGraphicsItem. The + following example shows how this is done: \code class Pixmap : public QObject, public QGraphicsPixmapItem @@ -209,164 +157,78 @@ Q_OBJECT Q_PROPERTY(QPointF pos READ pos WRITE setPos) ... + } \endcode - As described in the previous section, we need to define - properties that we wish to animate. + \note You can also derive from QGraphicsWidget, which already is a + QObject. - Note that QObject must be the first class inherited as the - meta-object system demands this. + As described in the previous section, you need to define + properties that you want to animate. The derived class must inherit + from QObject first as the meta-object system requires it. - \section1 Easing Curves + \section1 Easing curves - As mentioned, QPropertyAnimation performs an interpolation between - the start and end property value. In addition to adding more key - values to the animation, you can also use an easing curve. Easing - curves describe a function that controls how the speed of the - interpolation between 0 and 1 should be, and are useful if you - want to control the speed of an animation without changing the - path of the interpolation. + A QPropertyAnimation performs linear interpolation + between the start and end property values. In addition to adding more key + values to the animation, you can also choose an easing curve to control the + speed of interpolation between 0 and 1, without changing the + path. - \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(3000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); - animation.setEasingCurve(QEasingCurve::OutBounce); + \snippet code/src_corelib_animation_qpropertyanimation.cpp easing-curve - animation.start(); - \endcode - - Here the animation will follow a curve that makes it bounce like a - ball as if it was dropped from the start to the end position. - QEasingCurve has a large collection of curves for you to choose - from. These are defined by the QEasingCurve::Type enum. If you are - in need of another curve, you can also implement one yourself, and + In this example, the animation follows a curve that makes the + \c button bounce like a ball. QEasingCurve offers a large collection of curves + to choose from the QEasingCurve::Type enum. If you want + to use another curve that is not available, implement one yourself and register it with QEasingCurve. - \omit Drop this for the first Lab release - (Example of custom easing curve (without the actual impl of - the function I expect) - \endomit - - \section1 Putting Animations Together + \section1 Grouping animations - An application will often contain more than one animation. For - instance, you might want to move more than one graphics item + An application often contains more than one animation. For + example, it wants to move more than one graphics item simultaneously or move them in sequence after each other. - The subclasses of QAnimationGroup (QSequentialAnimationGroup and - QParallelAnimationGroup) are containers for other animations so + The subclasses of QAnimationGroup---QSequentialAnimationGroup and + QParallelAnimationGroup---are containers for other animations so that these animations can be animated either in sequence or - parallel. The QAnimationGroup is an example of an animation that - does not animate properties, but it gets notified of time changes - periodically. This enables it to forward those time changes to its - contained animations, and thereby controlling when its animations - are played. - - Let's look at code examples that use both - QSequentialAnimationGroup and QParallelAnimationGroup, starting - off with the latter. - - \code - QPushButton *bonnie = new QPushButton("Bonnie"); - bonnie->show(); - - QPushButton *clyde = new QPushButton("Clyde"); - clyde->show(); + parallel. The QAnimationGroup does not animate properties, but it + gets notified of time changes periodically. This enables it to + forward those time changes to the animation groups, which control when + their animations are played. - QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry"); - // Set up anim1 + The two following examples demonstrate the use of both + QSequentialAnimationGroup and QParallelAnimationGroup: - QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry"); - // Set up anim2 - - QParallelAnimationGroup *group = new QParallelAnimationGroup; - group->addAnimation(anim1); - group->addAnimation(anim2); - - group->start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp animation-group1 A parallel group plays more than one animation at the same time. - Calling its \l{QAbstractAnimation::}{start()} function will start - all animations it governs. - - \code - QPushButton button("Animated Button"); - button.show(); + Its \l{QAbstractAnimation::}{start()} function starts all + animations that are part of the group. - QPropertyAnimation anim1(&button, "geometry"); - anim1.setDuration(3000); - anim1.setStartValue(QRect(0, 0, 100, 30)); - anim1.setEndValue(QRect(500, 500, 100, 30)); - - QPropertyAnimation anim2(&button, "geometry"); - anim2.setDuration(3000); - anim2.setStartValue(QRect(500, 500, 100, 30)); - anim2.setEndValue(QRect(1000, 500, 100, 30)); - - QSequentialAnimationGroup group; - - group.addAnimation(&anim1); - group.addAnimation(&anim2); - - group.start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp animation-group2 - As you no doubt have guessed, QSequentialAnimationGroup plays + As the name suggests, a QSequentialAnimationGroup plays its animations in sequence. It starts the next animation in - the list after the previous is finished. + the list after the previous finishes. - Since an animation group is an animation itself, you can add - it to another group. This way, you can build a tree structure - of animations which specifies when the animations are played - in relation to each other. + A group is an animation itself, so you can add + it to another group. This way, building an animation tree, which define + when the animations are played in relation to each other. - \section1 Animations and States + \section1 Object ownership - When using a \l{The State Machine Framework}{state machine}, we - can associate one or more animations to a transition between states - using a QSignalTransition or QEventTransition class. These classes - are both derived from QAbstractTransition, which defines the - convenience function \l{QAbstractTransition::}{addAnimation()} that - enables the appending of one or more animations triggered when the - transition occurs. + 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 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: - We also have the possibility to associate properties with the - states rather than setting the start and end values ourselves. - Below is a complete code example that animates the geometry of a - QPushButton. - - \code - QPushButton *button = new QPushButton("Animated Button"); - button->show(); - - QStateMachine *machine = new QStateMachine; - - QState *state1 = new QState(machine); - state1->assignProperty(button, "geometry", QRect(0, 0, 100, 30)); - machine->setInitialState(state1); - - QState *state2 = new QState(machine); - state2->assignProperty(button, "geometry", QRect(250, 250, 100, 30)); - - QSignalTransition *transition1 = state1->addTransition(button, - &QPushButton::clicked, state2); - transition1->addAnimation(new QPropertyAnimation(button, "geometry")); - - QSignalTransition *transition2 = state2->addTransition(button, - &QPushButton::clicked, state1); - transition2->addAnimation(new QPropertyAnimation(button, "geometry")); - - machine->start(); - \endcode + \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 - For a more comprehensive example of how to use the state machine - framework for animations, see the states example (it lives in the - \c{examples/animation/states} directory). + \note You can also control the animation's lifespan by choosing a + \l{QAbstractAnimation::DeletionPolicy}{delete policy} while starting it. */ diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc new file mode 100644 index 0000000000..30d7ddaf60 --- /dev/null +++ b/src/corelib/doc/src/cbor.qdoc @@ -0,0 +1,79 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \group cbor + \title CBOR Support in Qt + \ingroup qt-basic-concepts + \brief An overview of CBOR support in Qt. + \ingroup explanations-dataprocessingandio + + \ingroup frameworks-technologies + + \keyword CBOR + + Qt provides support for dealing with CBOR data. CBOR is a binary format to + store data that has a superset of the types available in JSON, but is more + compact. + + The CBOR support in Qt provides an easy to use C++ API to parse, + modify and save CBOR data. + + More details about the CBOR data format can be found in \l {RFC 7049}. + + \tableofcontents + + \section1 Overview + + CBOR is a format to store structured data. It has three groups of built-in types: + + \list + \li Basic types: integers, floating point, boolean, null, etc. + \li String-like types: strings and byte arrays + \li Containers: arrays and maps + \endlist + + In addition, CBOR can add a "tag" to extend the meaning of the type. The + container types can contain basic types, string-like types and containers. + + \sa {Parsing and displaying CBOR data}, {Serialization Converter}, {Saving and Loading a Game} + + \section1 The CBOR Classes + + \section2 The QCborValue Class + + The QCborValue class represents any CBOR type. It also has a simple API for + reading and writing to QCborStreamReader and QCborStreamWriter objects, as + well as manipulating such objects in memory, with the help of QCborArray + and QCborMap. The CborValue API is simplified from the full CBOR data type + and always represents all integers as \l qint64 and all floating-point as + \c double. This means QCborValue is unable to represent CBOR integer values + outside of the range of \l qint64 (-2^63 to 2^63-1). When creating a CBOR + stream, QCborValue::toCbor() can be configured to attempt to write the + shorter single- and half-precision floating-point representations. + + \section2 The QCborArray Class + + The QCborArray class is used to hold an array of QCborValue objects. A + QCborValue object can contain a QCborArray object. It has functions for + converting to and from QVariantList, QStringList, QJsonArray. + + \section2 The QCborMap Class + + The QCborMap class is used to hold an map of QCborValue objects. A + QCborValue object can contain a QCborMap object. It has functions for + converting to and from QVariantMap, QVariantMap, and QJsonObject, but it + can have keys of any type, not just QString. + + \section2 The QCborStreamReader Class + + The QCborStreamReader class is a low level API for reading CBOR data from a + QIODevice, a QByteArray, or a pointer to memory. It has an API similar to + the QXmlStreamReader class. + + \section2 The QCborStreamWriter Class + + The QCborStreamWriter class is a low level API for writing CBOR data to a + QIODevice or a QByteArray. It has an API similar to the QXmlStreamWriter + class. +*/ diff --git a/src/corelib/doc/src/cmake-macros.qdoc b/src/corelib/doc/src/cmake-macros.qdoc deleted file mode 100644 index 8788554616..0000000000 --- a/src/corelib/doc/src/cmake-macros.qdoc +++ /dev/null @@ -1,416 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtcore-cmake-qt5-wrap-cpp.html -\ingroup cmake-macros-qtcore - -\title qt5_wrap_cpp - -\brief Creates \c{.moc} files from sources. - -\section1 Synopsis - -\badcode -qt5_wrap_cpp(<VAR> src_file1 [src_file2 ...] - [TARGET target] - [OPTIONS ...] - [DEPENDS ...]) -\endcode - -\section1 Description - -\include includes/qt_wrap_cpp.qdocinc description - -\note For compatibility with Qt 6, the command is also available under the name \l qt_wrap_cpp. - -\section1 Arguments - -\include includes/qt_wrap_cpp.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt5_wrap_cpp -*/ - -/*! -\page qtcore-cmake-qt-wrap-cpp.html -\ingroup cmake-macros-qtcore - -\title qt_wrap_cpp - -\brief Creates \c{.moc} files from sources. - -\section1 Synopsis - -\badcode -qt_wrap_cpp(<VAR> src_file1 [src_file2 ...] - [TARGET target] - [OPTIONS ...] - [DEPENDS ...]) -\endcode - -\section1 Description - -\include includes/qt_wrap_cpp.qdocinc description - -This command was introduced in Qt 5.15. You can use \l qt5_wrap_cpp in older versions of Qt. - -\section1 Arguments - -\include includes/qt_wrap_cpp.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt_wrap_cpp -*/ - -/*! -\page qtcore-cmake-qt5-add-resources.html -\ingroup cmake-macros-qtcore - -\title qt5_add_resources - -\brief Compiles binary resources into source code. - -\section1 Synopsis - -\badcode -qt5_add_resources(<VAR> file1.qrc [file2.qrc ...] - [OPTIONS ...]) -\endcode - -\section1 Description - -\include includes/qt_add_resources.qdocinc arguments - -For embedding bigger resources, see \l qt5_add_big_resources. - -\note For compatibility with Qt 6, the command is also available under the name \l qt_add_resources. - -\section1 Arguments - -\include includes/qt_add_resources.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt5_add_resources -*/ - -/*! -\page qtcore-cmake-qt-add-resources.html -\ingroup cmake-macros-qtcore - -\title qt_add_resources - -\brief Compiles binary resources into source code. - -\section1 Synopsis - -\badcode -qt_add_resources(<VAR> file1.qrc [file2.qrc ...] - [OPTIONS ...]) -\endcode - -\section1 Description - -\include includes/qt_add_resources.qdocinc arguments - -For embedding bigger resources, see \l qt_add_big_resources. - -This command was introduced in Qt 5.15. You can use \l qt5_add_resources in older versions of Qt. - -\section1 Arguments - -\include includes/qt_add_resources.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt_add_resources -*/ - -/*! -\page qtcore-cmake-qt5-add-big-resources.html -\ingroup cmake-macros-qtcore - -\title qt5_add_big_resources - -\brief Compiles big binary resources into object code. - -\section1 Synopsis - -\badcode -qt5_add_big_resources(<VAR> file1.qrc [file2.qrc ...] - [OPTIONS ...]) -\endcode - -\section1 Description - -\include includes/qt_add_big_resources.qdocinc description - -\note For compatibility with Qt 6, the command is also available under the name \l qt_add_big_resources. - -\section1 Arguments - -\include includes/qt_add_big_resources.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt5_add_big_resources -*/ - -/*! -\page qtcore-cmake-qt-add-big-resources.html -\ingroup cmake-macros-qtcore - -\title qt_add_big_resources - -\brief Compiles big binary resources into object code. - -\section1 Synopsis - -\badcode -qt_add_big_resources(<VAR> file1.qrc [file2.qrc ...] - [OPTIONS ...]) -\endcode - -\section1 Description - -\include includes/qt_add_big_resources.qdocinc description - -This command was introduced in Qt 5.15. You can use \l qt5_add_big_resources in older versions of Qt. - -\section1 Arguments - -\include includes/qt_add_big_resources.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt_add_big_resources -*/ - -/*! -\page qtcore-cmake-qt5_add_binary_resources.html -\ingroup cmake-macros-qtcore - -\title qt5_add_binary_resources - -\brief Creates an \c{RCC} file from a list of Qt resource files. - -\section1 Synopsis - -\badcode -qt5_add_binary_resources(target file1.qrc [file2.qrc ...] - [DESTINATION ...] - [OPTIONS ...]) -\endcode - -\section1 Description - -\include includes/qt_add_binary_resources.qdocinc description - -\note For compatibility with Qt 6, the command is also available under the name \l qt_add_binary_resources. - -\section1 Arguments - -\include includes/qt_add_binary_resources.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt5_add_binary_resources -*/ - -/*! -\page qtcore-cmake-qt_add_binary_resources.html -\ingroup cmake-macros-qtcore - -\title qt_add_binary_resources - -\brief Creates an \c{RCC} file from a list of Qt resource files. - -\section1 Synopsis - -\badcode -qt_add_binary_resources(target file1.qrc [file2.qrc ...] - [DESTINATION ...] - [OPTIONS ...]) -\endcode - -\section1 Description - -\include includes/qt_add_binary_resources.qdocinc description - -This command was introduced in Qt 5.15. You can use \l qt5_add_binary_resources in older versions of Qt. - -\section1 Arguments - -\include includes/qt_add_binary_resources.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt_add_binary_resources -*/ - -/*! -\page qtcore-cmake-qt5-generate-moc.html -\ingroup cmake-macros-qtcore - -\title qt5_generate_moc - -\brief Calls moc on an input file. - -\section1 Synopsis - -\badcode -qt5_generate_moc(src_file dest_file - [TARGET target]) -\endcode - -\section1 Description - -\include includes/qt_generate_moc.qdocinc description - -\note For compatibility with Qt 6, the command is also available under the name \l qt_generate_moc. - -\section1 Arguments - -\include includes/qt_generate_moc.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt5_generate_moc -*/ - -/*! -\page qtcore-cmake-qt-generate-moc.html -\ingroup cmake-macros-qtcore - -\title qt_generate_moc - -\brief Calls moc on an input file. - -\section1 Synopsis - -\badcode -qt_generate_moc(src_file dest_file - [TARGET target]) -\endcode - -\section1 Description - -\include includes/qt_generate_moc.qdocinc description - -This command was introduced in Qt 5.15. You can use \l qt5_generate_moc in older versions of Qt. - -\section1 Arguments - -\include includes/qt_generate_moc.qdocinc arguments - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt_generate_moc -*/ - -/*! -\page qtcore-cmake-qt5-import-plugins.html -\ingroup cmake-macros-qtcore - -\title qt5_import_plugins - -\brief Specifies a custom set of plugins to import for a static Qt build - -\section1 Synopsis - -\badcode -qt5_import_plugins(target - [INCLUDE plugin ...] - [EXCLUDE plugin ...] - [INCLUDE_BY_TYPE plugin_type plugin ...] - [EXCLUDE_BY_TYPE plugin_type]) -\endcode - -\section1 Description - -\include includes/qt_import_plugins.qdocinc description - -\note For compatibility with Qt 6, the command is also available under the name \l qt_import_plugins. - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt5_import_plugins - -In the snippet above, the following occurs with the executable \c myapp: - -\list -\li The \c Qt5::QCocoaIntegrationPlugin is imported into myapp. -\li The \c Qt5::QMinimalIntegrationPlugin plugin is - excluded from being automatically imported into myapp. -\li The default list of plugins for \c imageformats is - overridden to only include Qt5::QGifPlugin and Qt5::QJpegPlugin. -\li All \c sqldrivers plugins are excluded from automatic importing. -\endlist -*/ - -/*! -\page qtcore-cmake-qt-import-plugins.html -\ingroup cmake-macros-qtcore - -\title qt_import_plugins - -\brief Specifies a custom set of plugins to import for a static Qt build - -\section1 Synopsis - -\badcode -qt_import_plugins(target - [INCLUDE plugin ...] - [EXCLUDE plugin ...] - [INCLUDE_BY_TYPE plugin_type plugin ...] - [EXCLUDE_BY_TYPE plugin_type]) -\endcode - -\section1 Description - -\include includes/qt_import_plugins.qdocinc description - -This command was introduced in Qt 5.15. You can use \l qt5_import_plugins in older versions of Qt. - -\section1 Examples - -\snippet cmake-macros/examples.cmake qt_import_plugins - -In the snippet above, the following occurs with the executable \c myapp: - -\list -\li The \c Qt::QCocoaIntegrationPlugin is imported into myapp. -\li The \c Qt::QMinimalIntegrationPlugin plugin is - excluded from being automatically imported into myapp. -\li The default list of plugins for \c imageformats is - overridden to only include Qt::QGifPlugin and Qt::QJpegPlugin. -\li All \c sqldrivers plugins are excluded from automatic importing. -\endlist -*/ diff --git a/src/corelib/doc/src/cmake/cmake-commands.qdoc b/src/corelib/doc/src/cmake/cmake-commands.qdoc new file mode 100644 index 0000000000..e185bab624 --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-commands.qdoc @@ -0,0 +1,17 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-commands-qtcore +\title CMake Commands in Qt6 Core +\brief Lists CMake commands defined in Qt6::Core. + +The following CMake commands are defined when Qt6::Core is loaded, for instance +with + +\code +find_package(Qt6 REQUIRED COMPONENTS Core) +\endcode + +\sa{CMake Command Reference} +*/ diff --git a/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc new file mode 100644 index 0000000000..b710ba7275 --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-configure-variables.qdoc @@ -0,0 +1,587 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/* NOTE: The variables documented here are available when running CMake, they +** are not available in a deployment script. Both these and the set of +** deploy-time variables are all members of the cmake-variables-qtcore +** group. +**/ + +/*! +\group cmake-variables-qtcore +\title CMake Variables in Qt6 Core +\brief Lists CMake variables defined in Qt6::Core. + +The following CMake variables are defined when Qt6::Core is loaded, for instance +with + +\badcode +find_package(Qt6 REQUIRED COMPONENTS Core) +\endcode + +\sa{CMake Variable Reference} +*/ + +/*! +\page cmake-variable-android-ndk-host-system-name.html +\ingroup cmake-variables-qtcore + +\title ANDROID_NDK_HOST_SYSTEM_NAME +\target cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME + +\summary {Android-specific architecture of the host system.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +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()} +*/ + +/*! +\page cmake-variable-android-sdk-root.html +\ingroup cmake-variables-qtcore + +\title ANDROID_SDK_ROOT +\target cmake-variable-ANDROID_SDK_ROOT + +\summary {Location of the Android SDK.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +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()}. +*/ + +/*! +\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 + +\summary {List of arguments to pass to Android applications.} + +\cmakevariablesince 6.0 +\preliminarycmakevariable +\cmakevariableandroidonly + +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-deployment-type.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_DEPLOYMENT_TYPE +\target cmake-variable-QT_ANDROID_DEPLOYMENT_TYPE + +\summary {Forces or disables release package signing regardless of the build type.} + +\cmakevariablesince 6.7 +\preliminarycmakevariable +\cmakevariableandroidonly + +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} +*/ + +/*! +\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.} + +\cmakevariablesince 6.4.2 +\preliminarycmakevariable +\cmakevariableandroidonly + +Allows specifying the list of +CMake variables that need to be forwarded from the main ABI project to +ABI-specific subprojects. Due to the specifics of the Multi-ABI project build +process, there is no generic way to forward the CMake cache variables +that are specified either in the command line or in another similar way. + +A typical use case for the variable is propagating CMake cache variables +specified in the command line. For example, a project has two variables +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} that affect the +project configuration: +\badcode +cmake_minimum_required(VERSION 3.18) + +project(MyProject LANGUAGES CXX) + +find_package(Qt6 REQUIRED COMPONENTS Core) + +qt_add_executable(MyApp main.cpp) + +if(PROJECT_WIDE_VARIABLE1) + target_sources(MyApp PRIVATE sourcefile1.cpp) +endif() +if(PROJECT_WIDE_VARIABLE2) + target_sources(MyApp PRIVATE sourcefile2.cpp) +endif() +\endcode + +The above contents of \c{CMakeLists.txt} enable you to control how +\c{MyApp} is built by setting the corresponding CMake variables from the +command line: +\badcode +qt-cmake -S<source directory> -B<build directory> \ + -DPROJECT_WIDE_VARIABLE1=ON \ + -DPROJECT_WIDE_VARIABLE2=ON \ + -DQT_ANDROID_MULTI_ABI_FORWARD_VARS="PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2" +\endcode + +When configuring the application for desktop, \c{PROJECT_WIDE_VARIABLE1} and +\c{PROJECT_WIDE_VARIABLE2} are visible in CMake listings and scripts as global +cache variables. This doesn't work for Android Multi-ABI builds because +ABI-specific subprojects do not inherit the cache variables from the main-ABI +project. This issue can be solved by passing the list of required variables to +the \c{QT_ANDROID_MULTI_ABI_FORWARD_VARS} variable, so both +\c{PROJECT_WIDE_VARIABLE1} and \c{PROJECT_WIDE_VARIABLE2} values will be +propagated to the ABI-specific builds. + +The variable can be also defined in the project's CMakeLists.txt: +\badcode +... +qt_add_executable(MyApp main.cpp) +... +if(ANDROID) + set(QT_ANDROID_MULTI_ABI_FORWARD_VARS "PROJECT_WIDE_VARIABLE1;PROJECT_WIDE_VARIABLE2") +endif() +... +\endcode + +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 +finalization occurs automatically when using CMake 3.19 or later. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} +*/ + +/*! +\page cmake-variable-qt-android-build-all-abis.html +\ingroup cmake-variables-qtcore +\ingroup cmake-android-build-properties + +\title QT_ANDROID_BUILD_ALL_ABIS +\target cmake-variable-QT_ANDROID_BUILD_ALL_ABIS + +\summary {Enables building multi-ABI packages using the autodetected Qt for Android SDK list.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +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 +The typical directory structure looks as below: +\badcode +/path/to/Qt/6.x.x + android_armv7 + android_arm64_v8a + android_x86 + android_x86_64 + ... +\endcode +The auto-detected paths can be customized using one of \c{QT_PATH_ANDROID_ABI_<ABI>} variables. + +The variable is set to \c FALSE by default. + +\sa{QT_PATH_ANDROID_ABI_<ABI>} +*/ + +/*! +\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 + +\summary {List of ABIs that the project packages are built for.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +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. 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 +QT_ANDROID_ABIS logic. + +\sa{QT_PATH_ANDROID_ABI_<ABI>}, {QT_ANDROID_BUILD_ALL_ABIS} +*/ + +/*! +\page cmake-variable-qt-path-android-abi.html +\ingroup cmake-variables-qtcore + +\title QT_PATH_ANDROID_ABI_<ABI> +\target cmake-variable-QT_PATH_ANDROID_ABI_<ABI> + +\summary {Set of variables to specify the path to Qt for Android for the corresponding ABI.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +Each variable can be used to specify the path to Qt for Android for the corresponding ABI. +\include cmake-android-supported-abis.qdocinc + +\sa{cmake-variable-QT_ANDROID_ABIS}{QT_ANDROID_ABIS} +*/ + +/*! +\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 {Signs the .aab package with the specified keystore, alias, and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +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 + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +The mentioned variables are used internally by \l{androiddeployqt}. + +\sa{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 {Signs the package with the specified keystore, alias, and store password.} +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableandroidonly + +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 + QT_ANDROID_KEYSTORE_ALIAS + QT_ANDROID_KEYSTORE_STORE_PASS + QT_ANDROID_KEYSTORE_KEY_PASS +\endcode +The mentioned variables are used internally by \l{androiddeployqt}. + +\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 + +\title QT_NO_COLLECT_BUILD_TREE_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS + +\summary {Prevents collecting of project-built shared library targets during Android deployment.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\cmakevariableandroidonly + +During project finalization, the build system collects the locations of +all built shared library targets in the project. +These locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +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} +*/ + +/*! +\page cmake-variable-qt-no-collect-imported-target-apk-deps.html +\ingroup cmake-variables-qtcore + +\title QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS +\target cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS + +\summary {Prevents collecting of imported targets during Android deployment.} + +\cmakevariablesince 6.5 +\preliminarycmakevariable +\cmakevariableandroidonly + +When using CMake version 3.21 or later, the build system collects the locations of +imported shared library targets that might be relevant for deployment. +The collected targets are those that are reachable from the directory scope +of the currently processed executable target. That includes the target's source directory +scope and its parents. +The collected locations are passed to \l androiddeployqt for deployment consideration when +resolving dependencies between libraries. +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} +*/ + +/*! +\page cmake-variable-qt-host-path.html +\ingroup cmake-variables-qtcore + +\title QT_HOST_PATH +\target cmake-variable-QT_HOST_PATH + +\summary {Location of the host Qt installation when cross-compiling.} + +\cmakevariablesince 6.0 + +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). 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. +*/ + +/*! +\page cmake-variable-qt-no-set-xcode-development-team-id.html +\ingroup cmake-variables-qtcore + +\title QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID +\target cmake-variable-QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID + +\summary {Disables providing a fallback team ID during target finalization on iOS.} + +\cmakevariablesince 6.1 + +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. +To prevent this, set \c QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-no-set-xcode-bundle-identifier.html +\ingroup cmake-variables-qtcore + +\title QT_NO_SET_XCODE_BUNDLE_IDENTIFIER +\target cmake-variable-QT_NO_SET_XCODE_BUNDLE_IDENTIFIER + +\summary {Disables providing a fallback app bundle ID during target finalization on iOS.} + +\cmakevariablesince 6.1 + +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. +To prevent this, set \c QT_NO_SET_XCODE_BUNDLE_IDENTIFIER to \c TRUE. +*/ + +/*! +\page cmake-variable-qt-enable-verbose-deployment.html +\ingroup cmake-variables-qtcore + +\title QT_ENABLE_VERBOSE_DEPLOYMENT +\target cmake-variable-QT_ENABLE_VERBOSE_DEPLOYMENT + +\summary {Enables verbose mode of deployment tools.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable + +Enables verbose mode of the \l androiddeployqt deployment tool when it is called +internally at build time, usually during target finalization. + +This variable also changes the default verbosity of install-time deployment +scripts for other platforms (see \l{qt6_deploy_runtime_dependencies()}), but it +must be set before the first \c{find_package(Qt6)} call to have that effect. +*/ + +/*! +\page cmake-variable-qt-deploy-support.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_SUPPORT +\target cmake-variable-QT_DEPLOY_SUPPORT + +\summary {Name of the file to include for setting up deployment support.} + +\cmakevariablesince 6.3 +\preliminarycmakevariable +\note The value of this variable should never be modified by project code. + +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 +part of a post-build rule. + +The following example shows one way the variable would be used when installing +an application, along with its runtime dependencies: + +\include cmake-deploy-modified-variable-values.qdocinc + +\sa {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}, + {qt6_deploy_qml_imports}{qt_deploy_qml_imports()} +*/ + +/*! +\page cmake-variable-qt-no-standard-project-setup.html +\ingroup cmake-variables-qtcore + +\title QT_NO_STANDARD_PROJECT_SETUP +\target cmake-variable-QT_NO_STANDARD_PROJECT_SETUP + +\summary {Prevents subsequent calls to qt_standard_project_setup() from making any changes.} + +\cmakevariablesince 6.3 + +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 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 \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.} + +\cmakevariablesince 6.4 +\preliminarycmakevariable +\cmakevariableiosonly + +Specifies the path to an iOS launch screen storyboard file that will be used +by all targets within a project. + +\sa {Launch Screens and Launch Images} +*/ diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc new file mode 100644 index 0000000000..ac5094e7cb --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc @@ -0,0 +1,307 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/* NOTE: The variables documented here are available when running a deploy +** script, they are not available at configure time (i.e. when running +** CMake). Both these and the set of configure-time variables are all +** members of the cmake-variables-qtcore group. +**/ + +/*! +\page cmake-variable-qt-deploy-prefix.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_PREFIX +\target cmake-variable-QT_DEPLOY_PREFIX + +\summary {Base location for a deployment.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +\c{QT_DEPLOY_PREFIX} provides the base deployment directory. The other +\c{QT_DEPLOY_..._DIR} variables should be treated as relative to this location. +The value of \c{QT_DEPLOY_PREFIX} may be relative or absolute, so projects +should not assume one or the other in any given situation. A relative path is +expected to be treated as relative to the current working directory, as seen +by the build tool (ninja, make, and so on) at install time. + +The default value is \c{$ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}}, which is the +base location CMake uses during installation. If that evaluates to an empty +string, the default value will be a dot (.) instead, which is generally the +appropriate value when deploying as part of a post-build rule. This two-step +fallback logic ensures that projects can assume \c{QT_DEPLOY_PREFIX} will not +be an empty string, so it can safely be used as part of a path like +\c{${QT_DEPLOY_PREFIX}/${QT_DEPLOY_BIN_DIR}}. + +To change the value of \c QT_DEPLOY_PREFIX, the project can be configured +with a custom \l CMAKE_INSTALL_PREFIX as described in +\l {Command Line cmake invocation}. + +The \l DESTDIR environment variable can also be used to modify the final +installation, and thus deployment, location. + +Projects should rarely need to use this variable. In typical scenarios, deploy +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_LIBEXEC_DIR, + QT_DEPLOY_LIB_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, + QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-bin-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_BIN_DIR +\target cmake-variable-QT_DEPLOY_BIN_DIR + +\summary {Prefix-relative subdirectory for deploying runtime binaries on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +Projects should use \c QT_DEPLOY_BIN_DIR in their deploy scripts to avoid +hard-coding a particular directory in which to deploy the following types of +binaries: + +\list +\li Executables on all platforms. +\li DLLs on Windows. +\endlist + +\c QT_DEPLOY_BIN_DIR defaults to the value of \c${CMAKE_INSTALL_BINDIR} +(usually \c{bin}), which is provided by CMake's \l{GNUInstallDirs} module. +To change the value of \c QT_DEPLOY_BIN_DIR, ensure that the project sets +\c{CMAKE_INSTALL_BINDIR} before the \c Core package is found. + +The \c QT_DEPLOY_BIN_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-runtime-dependencies.qdocinc + +\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 +*/ + +/*! +\page cmake-variable-qt-deploy-lib-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_LIB_DIR +\target cmake-variable-QT_DEPLOY_LIB_DIR + +\summary {Prefix-relative subdirectory for deploying libraries on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +Projects should use \c QT_DEPLOY_LIB_DIR in their deploy scripts to avoid +hard-coding a particular directory in which to deploy the following types of +binaries: + +\list +\li Shared libraries on platforms other than Windows. +\li Import libraries on Windows. +\endlist + +\c QT_DEPLOY_LIB_DIR defaults to the value of \c${CMAKE_INSTALL_LIBDIR} +(usually \c{lib} or \c{lib64}), which is provided by +CMake's \l{GNUInstallDirs} module. +To change the value of \c QT_DEPLOY_LIB_DIR, ensure that the project sets +\c{CMAKE_INSTALL_LIBDIR} before the \c Core package is found. + +The \c QT_DEPLOY_LIB_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_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-plugins-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_PLUGINS_DIR +\target cmake-variable-QT_DEPLOY_PLUGINS_DIR + +\summary {Prefix-relative subdirectory for deploying Qt plugins on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +Projects should use \c QT_DEPLOY_PLUGINS_DIR in their deploy scripts to avoid +hard-coding a particular directory under which to deploy plugins. + +\c QT_DEPLOY_PLUGINS_DIR defaults to the value \c{plugins}. To change the value +of \c QT_DEPLOY_PLUGINS_DIR, set it in the project deployment script +before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_PLUGINS_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. Apple's macOS app bundle guidelines +require all plugins to be deployed to the \c{PlugIns} subdirectory of the +bundle contents. + +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + +\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 +*/ + +/*! +\page cmake-variable-qt-deploy-qml-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_QML_DIR +\target cmake-variable-QT_DEPLOY_QML_DIR + +\summary {Prefix-relative subdirectory for deploying QML plugins on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.3 + +Projects should use \c QT_DEPLOY_QML_DIR in their deploy scripts to avoid +hard-coding a particular directory under which to deploy QML modules. + +\c QT_DEPLOY_QML_DIR defaults to the value \c{qml}. To change the value +of \c QT_DEPLOY_QML_DIR, set it in the project deployment script +before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_QML_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. Apple's macOS app bundle guidelines +require all plugins to be deployed to the \c{PlugIns} subdirectory of the +bundle contents, and all other non-binary files should generally be under the +\c{Resources} subdirectory. The different parts of a QML module therefore need +to be deployed to different locations within the app bundle. + +\section1 Example + +\include cmake-deploy-modified-variable-values.qdocinc + +\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 +*/ + +/*! +\page cmake-variable-qt-deploy-translations-dir.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_TRANSLATIONS_DIR +\target cmake-variable-QT_DEPLOY_TRANSLATIONS_DIR + +\summary {Prefix-relative subdirectory for deploying Qt translations on some target platforms.} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.5 + +Projects should use \c QT_DEPLOY_TRANSLATIONS_DIR in their deploy scripts to +avoid hard-coding a particular directory under which to deploy translations. + +\c QT_DEPLOY_TRANSLATIONS_DIR defaults to the value \c{translations}. To change +the value of \c QT_DEPLOY_TRANSLATIONS_DIR, set it in the project deployment +script before \c QT_DEPLOY_SUPPORT is included. + +The \c QT_DEPLOY_TRANSLATIONS_DIR path is relative to \l{QT_DEPLOY_PREFIX}. + +This variable is not meaningful when deploying on macOS or Windows. + +\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_LIBEXEC_DIR, QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR +*/ + +/*! +\page cmake-variable-qt-deploy-ignored-lib-dirs.html +\ingroup cmake-variables-qtcore + +\title QT_DEPLOY_IGNORED_LIB_DIRS +\target cmake-variable-QT_DEPLOY_IGNORED_LIB_DIRS + +\summary {Directories that are excluded from runtime dependencies search} + +\include cmake-deploy-var-usage.qdocinc + +\cmakevariablesince 6.5 + +This variable contains a list of directories that are not taken into account +when searching for runtime dependencies with \l{qt_deploy_runtime_dependencies}. + +Projects may alter this variable before calling +\l{qt_deploy_runtime_dependencies} to control from which directory runtime +dependencies are deployed. + +This variable is ignored if the \c{POST_EXCLUDE_REGEXES} option is specified in +the \l{qt_deploy_runtime_dependencies} call. + +This variable is not meaningful when deploying on macOS or Windows. + +\sa qt_deploy_runtime_dependencies +*/ diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc new file mode 100644 index 0000000000..8fe2b0e88f --- /dev/null +++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc @@ -0,0 +1,637 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\group cmake-target-properties-qtcore +\title CMake Target Properties in Qt6 Core +\brief Lists CMake target properties known to Qt6::Core. + +\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following CMake +target properties: + +\sa{CMake Property Reference} +*/ + +/*! +\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 + +\brief Overrides the Qt dependencies added to the target's deployment. + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +By default, \l androiddeployqt will detect the dependencies of your +application. However, since run-time usage of plugins cannot be detected, +there could be false positives, as your application might depend on any +plugin that is a potential dependency. If you want to minimize the size of +your \c APK, it's possible to override the automatic detection using this +property. This should contain a list of all Qt files which need to be +included, with paths relative to the Qt install root. + +\note Only the Qt files specified with this variable are included. Failing +to include all the correct files can result in crashes. It's also important +to make sure the files are listed in the correct loading order. This variable +provides a way to override the automatic detection entirely, so if a library +is listed before its dependencies, it will fail to load on some devices. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {Extra libraries to deploy with the target.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +A list of external libraries that will be copied into your application's +\c libs folder and loaded on start-up. This can be used, for instance, +to enable OpenSSL in your application. For more information, see +\l{Adding OpenSSL Support for Android}. + +When adding extra libraries from the build tree of your project, it's also +necessary to add dependency relations between library and the application +target. Using the following project structure may cause an issue, when deploying +an apk: +\badcode +qt_add_executable(MyApp main.cpp) + +set_target_properties(MyApp PROPERTIES + QT_ANDROID_EXTRA_LIBS + ${CMAKE_CURRENT_BINARY_DIR}/libMyService_${ANDROID_ABI}.so +) + +# MyService library doesn't have any relations with MyApp +qt_add_library(MyService service.cpp) +\endcode + +This leads to uncertainty whether MyService library will be available before +the deployment of MyApp or not. The easiest solution is adding MyService +library to the MyApp dependencies: +\badcode +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()} +*/ + +/*! +\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 + +\summary {Extra Qt plugins to deploy with the target.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies a path to C++ plugins or resources that your application has to bundle +but that cannot be delivered through the assets system, such as QML plugins. +With this variable, \l androiddeployqt will make sure everything is packaged +and deployed properly. + +\c QT_ANDROID_EXTRA_PLUGINS must point to the directory where the extra plugin(s) +are built. In addition, the build directory structure must follow a naming +convention similar to Qt plugins, that is, \e {plugins/<plugin name>}. +\c QT_ANDROID_EXTRA_PLUGINS should point to the \e {plugins} part of that path. + +The plugins libraries should have the name format +\e {libplugins_<type>_<name>_<abi>.so}. This will ensure that the correct name +mangling is applied to the plugin library. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {Minimum Android SDK version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the minimum Android API level for the target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {Path to a custom Android package template.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the path for a custom Android package template. The Android package +template contains: +\list + \li AndroidManifest.xml file + \li build.gradle file and other Gradle scripts + \li res/values/libs.xml file +\endlist + +The path specified by this variable can contain custom Java classes under +\c src directory. By default, the \l androiddeployqt tool copies the +application template from the Qt for Android installation path into your +project's build directory, then it copies the contents of the path specified +by this variable on top of that, overwriting any existing files. For +instance, you can make a custom \c {AndroidManifest.xml} for your application, +then place this directly into the directory specified by this variable. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {Android target SDK version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the target Android API level for the target. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {Revision of Android build tools to use.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the Android SDK build tools revision to use. If this is not set then +CMake will attempt to use the latest installed version. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-version-code.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_ANDROID_VERSION_CODE +\target cmake-target-property-QT_ANDROID_VERSION_CODE +\ingroup cmake-android-manifest-properties + +\summary {Internal Android app version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the app's version number. This is usually a number that +increments monotonically with each release of your project. + +For more information, see \l{Android: App Versioning}{Android App Versioning}. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-android-version-name.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_ANDROID_VERSION_NAME +\target cmake-target-property-QT_ANDROID_VERSION_NAME +\ingroup cmake-android-manifest-properties + +\summary {Human-readable Android app version.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +Specifies the app's version as a human readable string, usually three +numbers, separated by dots. + +For more information, see \l{Android: App Versioning}{Android App Versioning}. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {List of ABIs that packages of a single target are built for.} + +\cmakepropertysince 6.3 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +By setting the \c{QT_ANDROID_ABIS} property for a target, it's possible to control +the list of ABIs that the single target packages are supposed to be built for. +\include cmake-android-supported-abis.qdocinc +The property only affects targets created with +\l{qt6_add_executable}{qt_add_executable()}. + +\sa{cmake-variable-QT_ANDROID_ABIS}{QT_ANDROID_ABIS}, {QT_ANDROID_BUILD_ALL_ABIS} +*/ + +/*! +\page cmake-target-property-qt-qml-root-path.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_QML_ROOT_PATH +\target cmake-target-property-QT_QML_ROOT_PATH + +\summary {Overrides the location of the application's qml directory.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty + +This property is currently only used when generating a deployment settings file +for Android. If the property is set, it specifies the path to the application's +\c{qml} directory. If it is not set, the \c{SOURCE_DIR} property of the target +will be used instead. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\page cmake-target-property-qt-qml-import-path.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_QML_IMPORT_PATH +\target cmake-target-property-QT_QML_IMPORT_PATH + +\summary {Specifies a list of directories to search for QML imports.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty + +This property is currently only used when generating a deployment settings file +for Android. It typically contains just the path to Qt's \c{qml} directory, but +it can be a list that contains other locations to be searched as well. +For application-specific QML imports, use +\l{cmake-target-property-QT_QML_ROOT_PATH}{QT_QML_ROOT_PATH} instead. + +\sa{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()} +*/ + +/*! +\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 + +\summary {Specifies the location of a target's generated deployment settings file.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty +\cmakepropertyandroidonly + +This property will be set by +\l{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. +Projects should not try to set this property themselves, as it will be ignored +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 + +\summary {Specifies the location of Qt libraries on the target device.} + +\preliminarycmakeproperty +\cmakepropertyandroidonly + +This property can be set to provide a path to Qt libraries on the target device, +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 + +\summary {Whether Qt shared libraries are packaged in the APK on Android.} + +\preliminarycmakeproperty +\cmakepropertyandroidonly + +This property can be set to not package Qt shared libraries inside the APK when +deploying the target. Use +\l{cmake-target-property-QT_ANDROID_SYSTEM_LIBS_PREFIX}{QT_ANDROID_SYSTEM_LIBS_PREFIX} +to provide a path to where those libraries will be located on the target device +instead. + +\note Only supported when deploying as an APK. +*/ + +/*! +\page cmake-target-property-qt-no-entrypoint.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title qt_no_entrypoint +\target cmake-target-property-qt_no_entrypoint + +\summary {Specifies to inhibit linking against Qt's entrypoint lib.} + +\cmakepropertysince 6.1 +\preliminarycmakeproperty + +On certain platforms, Qt applications link against Qt's entrypoint lib by default. +That library provides implementations of main (or WinMain). + +On targets that must provide their own entry point, set the property \c qt_no_entrypoint to inhibit linking against Qt's entrypoint library. +*/ + +/*! +\page cmake-target-property-qt-resource-prefix.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_RESOURCE_PREFIX +\target cmake-target-property-QT_RESOURCE_PREFIX + +\summary {Specifies the default Qt resource prefix.} + +\cmakepropertysince 6.0 +\preliminarycmakeproperty + +When using \l{qt6_add_resources}{qt_add_resources} without a \c PREFIX +argument, then the value of this target property will be used as +resource prefix. +*/ + +/*! +\group cmake-source-file-properties-qtcore +\title CMake Source File Properties in Qt6 Core +\brief Lists CMake file properties used in Qt6::Core. + +\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following CMake +source file properties: + +\sa{CMake Property Reference} +*/ + +/*! +\page cmake-source-file-property-qt-resource-alias.html +\ingroup cmake-source-file-properties-qtcore + +\title QT_RESOURCE_ALIAS +\target cmake-source-file-property-QT_RESOURCE_ALIAS + +\summary {Specifies the Qt resource alias for a file in a resource.} + +\cmakepropertysince 6.0 + +When using the target-based variant of \l{qt6_add_resources}{qt_add_resources} +the property value overrides the runtime path where the resource file is found. + +\sa{The Qt Resource System} +*/ + +/*! +\page cmake-source-file-property-qt-discard-file-contents.html +\ingroup cmake-source-file-properties-qtcore + +\title QT_DISCARD_FILE_CONTENTS +\target cmake-source-file-property-QT_DISCARD_FILE_CONTENTS + +\summary {Specifies that the given files should be empty in the resource file system} + +\cmakepropertysince 6.6 +\preliminarycmakeproperty + +When using the target-based variant of \l{qt6_add_resources}{qt_add_resources} +or \l{qt_add_qml_module}, setting this property to \c TRUE causes the file +contents to be omitted when creating the resource file system. The file name is +retained. + +This is useful if you want to strip QML source code from the binary. + +\note If you omit the QML source code from the binary, the QML engine has to +rely on the compilation units created by \l{qmlcachegen} or \l{qmlsc}. +Those are tied to the specific version of Qt they were built with. If you change +the version of Qt your application uses, they can't be loaded anymore. + +\sa{The Qt Resource System} +*/ + +/*! +\page cmake-target-property-qt-wasm-pthread-pool-size.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_WASM_PTHREAD_POOL_SIZE +\target cmake-target-property-QT_WASM_PTHREAD_POOL_SIZE + +\summary {Internal WebAssembly thread pool size.} + +\cmakepropertysince 6.2.4 +\preliminarycmakeproperty +\cmakepropertywebassemblyonly + +Specifies the number of web workers (threads) to create at application startup. +Qt allocates a pool size of 4 by default. This means the app can use +4 additional threads besides the main thread, without the additional overhead +of creating a new web worker, which may deadlock if the main thread created it +and join()s the thread without returning control to the event loop first. +Translates into the Emscripten compiler setting of PTHREAD_POOL_SIZE. + +For more information, see \l{https://emscripten.org/docs/porting/pthreads.html}{Pthreads support}. +*/ + +/*! +\group cmake-global-properties-qtcore +\title CMake Global Properties in Qt6 Core +\brief Lists CMake global properties used or defined in Qt6::Core. + +\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following global +CMake properties: + +\sa{CMake Property Reference} +*/ + +/*! +\page cmake-global-property-qt-targets-folder.html +\ingroup cmake-properties-qtcore +\ingroup cmake-global-properties-qtcore + +\title QT_TARGETS_FOLDER +\target cmake-global-property-QT_TARGETS_FOLDER + +\brief Sets the FOLDER property for Qt-internal targets. + +\cmakepropertysince 6.5 +\preliminarycmakeproperty + +Name of the \l FOLDER for internal targets that are added by Qt's CMake +commands. + +By default, this property is not set. + +This property only has an effect if CMake's \l USE_FOLDERS property is \c{ON}. + +You can use the \l{qt6_standard_project_setup}{qt_standard_project_setup} +function to enable folder support and initialize the \c{QT_TARGETS_FOLDER}. + +\sa{qt6_standard_project_setup}{qt_standard_project_setup} +*/ + +/*! +\page cmake-target-property-qt-wasm-initial-memory.html +\ingroup cmake-properties-qtcore +\ingroup cmake-target-properties-qtcore + +\title QT_WASM_INITIAL_MEMORY +\target cmake-target-property-QT_WASM_INITIAL_MEMORY + +\summary {Internal WebAssembly initial memory.} + +\cmakepropertysince 6.2.4 +\preliminarycmakeproperty +\cmakepropertywebassemblyonly + +Specifies the initial amount of memory to use, in bytes. Using more will cause the +browser to copy the old heap into a new one. Translates into the +Emscripten compiler setting of INITIAL_MEMORY. +QT_WASM_INITIAL_MEMORY must be a multiple of 65536 bytes. + +For more information, see \l{https://github.com/emscripten-core/emscripten/blob/main/src/settings.js}{Emscripten compiler settings}. +*/ + +/*! +\page cmake-target-property-qt-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 + +\title QT_IOS_LAUNCH_SCREEN +\target cmake-target-property-QT_IOS_LAUNCH_SCREEN + +\summary {Path to iOS launch screen storyboard} + +\cmakepropertysince 6.4 +\preliminarycmakeproperty +\cmakepropertyiosonly + +Specifies the path to an iOS launch screen storyboard file. + +\sa {Launch Screens and Launch Images} +*/ diff --git a/src/corelib/doc/src/cmake/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 new file mode 100644 index 0000000000..a40344a167 --- /dev/null +++ b/src/corelib/doc/src/cmake/policy/qtp0002.qdoc @@ -0,0 +1,63 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-cmake-policy-qtp0002.html +\ingroup qt-cmake-policies + +\title QTP0002 +\keyword qt_cmake_policy_qtp0002 + +\summary {Target properties that specify Android-specific paths may contain generator expressions.} + +This policy was introduced in Qt 6.6. It changes the processing of target +properties that specify Android-specific paths: +\list + \li \l QT_QML_IMPORT_PATH + \li \l QT_QML_ROOT_PATH + \li \l QT_ANDROID_PACKAGE_SOURCE_DIR + \li \l QT_ANDROID_EXTRA_PLUGINS + \li \l QT_ANDROID_EXTRA_LIBS +\endlist + +The \c OLD behavior of this policy doesn't allow generator expressions in the +target properties that specify Android-specific paths but implicitly converts +the specified paths to valid JSON strings. + +The \c NEW behavior of this policy allows using generator expressions in the +target properties that specify Android-specific paths, but they must evaluate to +valid JSON strings. + +The following value of the \l QT_ANDROID_EXTRA_PLUGINS property is converted to +a valid JSON string if you set the policy to OLD, but leads to an error if the +policy is set to NEW: +\badcode +set_target_properties( + QT_ANDROID_EXTRA_PLUGINS "\\path\\to\\MyPlugin.so" +) +\endcode +If the policy is set to NEW for the above example, the resulting JSON string in +the deployment settings file will contain escaped symbols instead of path +separators. + +Generator expressions are only supported if the policy is set to NEW, so the +OLD behavior generates a malformed deployment settings file with the following +code: +\badcode +set_target_properties( + QT_ANDROID_EXTRA_PLUGINS "$<TARGET_FILE_DIR:MyPlugin>" +) +\endcode + +This property value works as expected with both OLD and NEW policy values: +\badcode +set_target_properties( + QT_ANDROID_EXTRA_PLUGINS "/path/to/MyPlugin.so" +) +\endcode + +\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_big_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc new file mode 100644 index 0000000000..8215d4c717 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_big_resources.qdoc @@ -0,0 +1,53 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-bigresources.html +\ingroup cmake-commands-qtcore + +\title qt_add_big_resources +\keyword qt6_add_big_resources + +\summary {Compiles big binary resources into object code.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.12 + +\section1 Synopsis + +\badcode +qt_add_big_resources(<VAR> file1.qrc [file2.qrc ...] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_big_resources() + +\section1 Description + +Creates compiled object files from Qt resource files using the +\l{Resource Compiler (rcc)}. Paths to the generated files are added to +\c{<VAR>}. + +This is similar to \l qt_add_resources, but directly +generates object files (\c .o, \c .obj) files instead of C++ source code. +This allows to embed bigger resources, where compiling to C++ sources and then +to binaries would be too time consuming or memory intensive. + +\note The \c{file1.qrc} will not be treated as a source file by Qt Creator. It +needs to be added as a source file to a CMake target and have the property +\c{SKIP_AUTORCC} set to \c{ON}. + +\warning This command is not supported when building for iOS, use +\l qt_add_resources instead. +See \l{https://bugreports.qt.io/browse/QTBUG-103497}{QTBUG-103497} for details. + +\section1 Arguments + +You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. +You can find possible options in the \l{rcc}{rcc documentation}. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_add_big_resources +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc new file mode 100644 index 0000000000..12ee5e1aff --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_binary_resources.qdoc @@ -0,0 +1,43 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-binary-resources.html +\ingroup cmake-commands-qtcore + +\title qt_add_binary_resources +\keyword qt6_add_binary_resources + +\summary {Creates an RCC file from a list of Qt resource files.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.10 + +\section1 Synopsis + +\badcode +qt_add_binary_resources(target file1.qrc [file2.qrc ...] + [DESTINATION ...] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_binary_resources() + +\section1 Description + +Adds a custom \c target that compiles Qt resource files into a binary \c{.rcc} +file. + +\section1 Arguments + +\c{DESTINATION} sets the path of the generated \c{.rcc} file. The default is +\c{${CMAKE_CURRENT_BINARY_DIR}/${target}.rcc}. + +You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. +You can find possible options in the \l{rcc}{rcc documentation}. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_add_binary_resources +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_executable.qdoc b/src/corelib/doc/src/cmake/qt_add_executable.qdoc new file mode 100644 index 0000000000..cc8c924c79 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_executable.qdoc @@ -0,0 +1,114 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-executable.html +\ingroup cmake-commands-qtcore + +\title qt_add_executable +\keyword qt6_add_executable + +\summary {Creates and finalizes an application target of a platform-specific type.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_add_executable(target + [WIN32] [MACOSX_BUNDLE] + [MANUAL_FINALIZATION] + sources...) +\endcode + +\versionlessCMakeCommandsNote qt6_add_executable() + +\section1 Description + +This command performs the following tasks: + +\list +\li Create a CMake target of the appropriate type for the target platform. +\li Link the target to the \c{Qt::Core} library. +\li Handle finalization of the CMake target. +\endlist + +\section2 Target Creation + +On all platforms except Android, an executable target will be created. +All arguments will be passed through to the standard CMake \c{add_executable()} +command, except \c{MANUAL_FINALIZATION} (if present). On Android, a \c{MODULE} +library will be created and any \c{WIN32} or \c{MACOSX_BUNDLE} options will be +ignored. Some target properties will also be set for Android: + +\list +\li The \c{SUFFIX} target property will be set to give the library file name an + architecture-specific suffix. +\li Various \c{<lang>_VISIBILITY_PRESET} target properties will be set to + \c{default} to ensure that the \c{main()} function is visible in the + resultant binary. +\endlist + +\section2 Linking Qt::Core + +Since all Qt applications need to link to the \c{Qt::Core} library, this is done +for you as a convenience. + +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps are +commonly needed. The steps to perform depend on the platform and on various +properties of the target. + +The finalization processing is implemented by two commands: +\l{qt6_finalize_target}{qt_finalize_target()} and +\l{qt6_finalize_project}{qt_finalize_project()}. + +Target finalization can occur either as part of calling \c{qt_add_executable} +or be deferred to sometime after this command returns (but it should still be in +the same directory scope). + +When using CMake 3.19 or later, target finalization is automatically deferred to the +end of the current directory scope. This gives the caller an opportunity to +modify properties of the created target before it is finalized. When using +CMake versions earlier than 3.19, automatic deferral isn't supported. In that +case, target finalization is performed immediately before this command returns. + +Regardless of the CMake version, the \c{MANUAL_FINALIZATION} keyword can be given to +indicate that you will explicitly call \l{qt6_finalize_target}{qt_finalize_target()} +yourself instead at some later time. In general, \c MANUAL_FINALIZATION should +not be needed unless the project has to support CMake 3.18 or earlier. + +Project finalization occurs automatically when using CMake 3.19 or later. +When using an older CMake version, you should call +\l{qt6_finalize_project}{qt_finalize_project()} manually, at the end +of the root \c CMakeLists.txt file. +This is especially important when targeting Android, to collect dependencies +between project targets for deployment purposes. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_set_finalizer_mode}{qt_set_finalizer_mode()}, + {qt6_add_library}{qt_add_library()}, + {qt6_finalize_project}{qt_finalize_project()} + +\section1 Examples + +In the following simple case, finalization is handled automatically. If using a +CMake version earlier than 3.19, finalization will be performed immediately as +part of the call. When using CMake 3.19 or later, finalization will occur at the +end of the current directory scope. + +\snippet cmake-macros/examples.cmake qt_add_executable_simple + +The following example shows a scenario where finalization must be deferred. +The \c OUTPUT_NAME target property affects deployment settings on Android, but +those settings are written out as part of finalizing the target. In order to +support using CMake versions earlier than 3.19, we take over responsibility +for finalizing the target by adding the \c{MANUAL_FINALIZATION} keyword. + +\snippet cmake-macros/examples.cmake qt_add_executable_deferred + +\include cmake-android-qt-finalize-project-warning.qdocinc warning +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_library.qdoc b/src/corelib/doc/src/cmake/qt_add_library.qdoc new file mode 100644 index 0000000000..851a2d6210 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_library.qdoc @@ -0,0 +1,80 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-library.html +\ingroup cmake-commands-qtcore + +\title qt_add_library +\keyword qt6_add_library + +\summary {Creates and finalizes a library.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_add_library(target + [STATIC | SHARED | MODULE | INTERFACE | OBJECT] + [MANUAL_FINALIZATION] + sources... +) +\endcode + +\versionlessCMakeCommandsNote qt6_add_library() + +\section1 Description + +\c{qt_add_library()} is a wrapper around CMake's built-in +\c{add_library()} command. It performs the following tasks: + +\list +\li Create a CMake target of an appropriate library type. +\li Handle finalization of the CMake target. +\endlist + +\section2 Target Creation + +The type of library created can be specified explicitly with one of the +\c STATIC, \c SHARED, \c MODULE, \c INTERFACE or \c OBJECT keywords, just as +one might for \c{add_library()}. If none of these keywords are given, the +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. +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()}. + +\target qt_add_library finalization +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps may be +needed. The finalization processing is implemented by the +\l{qt6_finalize_target}{qt_finalize_target()} command. + +Finalization can occur either as part of this call or be deferred to sometime +after this command returns (but it should still be in the same directory scope). +When using CMake 3.19 or later, finalization is automatically deferred to the +end of the current directory scope. This gives the caller an opportunity to +modify properties of the created target before it is finalized. When using +CMake versions earlier than 3.19, automatic deferral isn't supported. In that +case, finalization is performed immediately before this command returns. + +Regardless of the CMake version, the \c{MANUAL_FINALIZATION} keyword can be +given to indicate that you will explicitly call +\l{qt6_finalize_target}{qt_finalize_target()} yourself instead at some later +time. In general, \c MANUAL_FINALIZATION should not be needed unless the +project has to support CMake 3.18 or earlier. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()}, QTP0003 + +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_plugin.qdoc b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc new file mode 100644 index 0000000000..d2322086e7 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_plugin.qdoc @@ -0,0 +1,87 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-plugin.html +\ingroup cmake-commands-qtcore + +\title qt_add_plugin +\keyword qt6_add_plugin + +\summary {Creates a Qt plugin target.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_add_plugin(target + [SHARED | STATIC] + [CLASS_NAME class_name] + [OUTPUT_TARGETS variable_name] + [MANUAL_FINALIZATION] + sources... +) +\endcode + +The \c MANUAL_FINALIZATION option and the ability to set sources +were introduced in Qt 6.5. + +\versionlessCMakeCommandsNote qt6_add_plugin() + +\section1 Description + +Qt plugin targets have additional requirements over and above an ordinary CMake +library target. The \c{qt_add_plugin()} command adds the necessary handling to +ensure these requirements are met. It should be called rather than the built-in +CMake \c{add_library()} command when defining a Qt plugin target. + +By default, the plugin will be created as a \c STATIC library if Qt was built +statically, or as a \c MODULE library otherwise. You can override this default +by explicitly providing the \c STATIC or \c SHARED option. + +Any \c{sources} provided will be passed through to the internal call to +\c{add_library()}. + +\note Non-static plugins are meant to be loaded dynamically at runtime, not +linked to at build time. CMake differentiates between these two scenarios by +providing the \c MODULE library type for dynamically loaded libraries, and +the \c SHARED library type for libraries that may be linked to directly. This +distinction is important for some toolchains (notably Visual Studio), due to +the way symbol exports are handled. It may not be possible to link to +\c MODULE libraries, and generating a \c SHARED library with no exported +symbols can result in build-time errors. If the \c SHARED option is passed to +\c{qt_add_plugin()}, it will therefore create a \c MODULE library rather than a +\c SHARED library. + +Every Qt plugin has a class name. By default, this will be the same as the +\c target, but it can be overridden with the \c CLASS_NAME option. The class +name corresponds to the name of the C++ class that declares the metadata for +the plugin. For static plugins, it is also the name passed to +\l Q_IMPORT_PLUGIN, which imports the plugin into an application and ensures it +is available at run time. + +If the plugin is built statically, \c{qt_add_plugin()} may define additional +internal targets. These facilitate automatic importing of the plugin for any +executable or shared library that links to the plugin. If the project installs +the plugin and intends to make it available for other projects to link to, the +project should also install these internal targets. The names of these targets +can be obtained by providing the \c OUTPUT_TARGETS option, followed by the name +of a variable in which to return the target list. + +\section2 Finalization + +After a target is created, further processing or \e{finalization} steps may be +needed. The finalization processing is implemented by the +\l{qt6_finalize_target}{qt_finalize_target()} command. + +For details and the meaning of the \c{MANUAL_FINALIZATION} option, refer to the +\l{qt_add_library finalization}{finalization documentation} for +\c{qt_add_library}. + +\sa {qt6_finalize_target}{qt_finalize_target()}, + {qt6_add_executable}{qt_add_executable()} + +*/ diff --git a/src/corelib/doc/src/cmake/qt_add_resources.qdoc b/src/corelib/doc/src/cmake/qt_add_resources.qdoc new file mode 100644 index 0000000000..2e713b1b8e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_add_resources.qdoc @@ -0,0 +1,110 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-add-resources.html +\ingroup cmake-commands-qtcore + +\title qt_add_resources +\keyword qt6_add_resources + +\summary {Compiles binary resources into source code.} + +\include cmake-find-package-core.qdocinc + +\section1 Synopsis + +\badcode +qt_add_resources(<VAR> file1.qrc [file2.qrc ...] + [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_resources() + +Since 6.0: + +\badcode +qt_add_resources(<TARGET> <RESOURCE_NAME> + [PREFIX <PATH>] + [LANG <LANGUAGE>] + [BASE <PATH>] + [BIG_RESOURCES] + [OUTPUT_TARGETS <VARIABLE_NAME>] + [FILES ...] [OPTIONS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_add_resources() + +\section1 Description + +To add resources, you can pass either a variable name or a target as the first +argument of the command. + +When passing a variable name as first argument, \c qt_add_resources creates +source code from Qt resource files using the \l{Resource Compiler (rcc)}. Paths +to the generated source files are added to \c{<VAR>}. + +When passing a target as first argument, the function creates a resource with +the name \c{RESOURCE_NAME}, containing the specified \c{FILES}. The resource is +automatically linked into \c{TARGET}. + +See \l{The Qt Resource System} for a general description of Qt resources. + +\section1 Arguments of the target-based variant + +\c PREFIX specifies a path prefix under which all files of this resource are +accessible from C++ code. This corresponds to the XML attribute \c prefix of the +\c .qrc file format. If \c PREFIX is not given, the target property +\l{cmake-target-property-QT_RESOURCE_PREFIX}{QT_RESOURCE_PREFIX} is used. Since +6.5, \c{PREFIX} is optional. If it is omitted and not specified by +\c{QT_RESOURCE_PREFIX}, \c{"/"} will be used as the default path prefix. + +\c LANG specifies the locale of this resource. This corresponds to the XML +attribute \c lang of the \c .qrc file format. + +\c BASE is a path prefix that denotes the root point of the file's alias. For +example, if \c BASE is \c{"assets"} and \c FILES is +\c{"assets/images/logo.png"}, then the alias of that file is +\c{"images/logo.png"}. + +Alias settings for files need to be set via the \c QT_RESOURCE_ALIAS source file +property. + +\c BIG_RESOURCES can be specified to enable support for big resources. This +directly generates object files (\c .o, \c .obj) instead of C++ source code. +This allows embedding bigger resources, without having to compile generated C++ +sources, which can be too time consuming and memory intensive. + +Note that \c BIG_RESOURCES is not compatible with iOS due to restrictions of +CMake's Xcode project generator. See +\l{https://bugreports.qt.io/browse/QTBUG-103497}{QTBUG-103497} for details. +Also, \c BIG_RESOURCES only works reliably from CMake 3.17 onwards. + +When using this command with static libraries, one or more special targets will +be generated. Should you wish to perform additional processing on these targets, +pass a variable name to the \c OUTPUT_TARGETS parameter. The \c qt_add_resources +function stores the names of the special targets in the specified variable. + +\section1 Arguments of both variants + +You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. +You can find possible options in the \l{rcc}{rcc documentation}. + +\section1 Examples + +Variable variant, using a .qrc file: +\snippet cmake-macros/examples.cmake qt_add_resources + +Target variant, using immediate resources: +\snippet cmake-macros/examples.cmake qt_add_resources_target + +\section1 Caveats + +When adding multiple resources, \c{RESOURCE_NAME} must be unique across all +resources linked into the final target. + +This especially affects static builds. There, the same resource name in +different static libraries conflict in the consuming target. + +\sa {qt6_add_big_resources}{qt_add_big_resources()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc new file mode 100644 index 0000000000..ad95401f4d --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_allow_non_utf8_sources.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-allow-non-utf8-sources.html +\ingroup cmake-commands-qtcore + +\title qt_allow_non_utf8_sources +\keyword qt6_allow_non_utf8_sources + +\summary {Prevents forcing source files to be treated as UTF-8 for Windows.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 + +\section1 Synopsis + +\badcode +qt_allow_non_utf8_sources(target) +\endcode + +\versionlessCMakeCommandsNote qt6_allow_non_utf8_sources() + +\section1 Description + +When building with some compilers for Windows, targets that link to a Qt library +will use flags that force the compiler to treat its source files as UTF-8. This +is currently implemented for Visual Studio and Intel compilers. You can disable +this behavior on a per-target basis by calling \c{qt_allow_non_utf8_sources()} +and passing the target as the argument. + +\sa {qt6_disable_unicode_defines}{qt_disable_unicode_defines()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc new file mode 100644 index 0000000000..b2415730f5 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_android_add_apk_target.qdoc @@ -0,0 +1,55 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-android-add-apk-target.html +\ingroup cmake-commands-qtcore + +\title qt_android_add_apk_target +\keyword qt6_android_add_apk_target + +\summary {Defines a build target that runs androiddeployqt to produce an APK.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable instead. +\cmakecommandandroidonly + +\section1 Synopsis + +\badcode +qt_android_add_apk_target(target) +\endcode + +\versionlessCMakeCommandsNote qt6_android_add_apk_target() + +\section1 Description + +The \c{<target>_make_apk} and \c{<target>_make_aab} custom targets created by +this command take an Android deployment settings file and generate APK and +AAB respectively by running \c{androiddeployqt}. +The location of the settings file is taken from the \c{target}'s +\c{QT_ANDROID_DEPLOYMENT_SETTINGS_FILE} property. This file is typically created by +\l{qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}. +The respective Android package will be generated in an \c{android-build} +subdirectory below the CMake build directory of the \c{target}. + +The \c{<target>_make_apk} and \c{<target>_make_aab} targets will be +automatically added as dependencies of the \c{apk} and \c{aab} build targets +respectively, which will be created automatically. Creating of the \c{apk} and +\c{aab} targets can be disabled by setting the \c{QT_NO_GLOBAL_APK_TARGET} and +\c{QT_NO_GLOBAL_AAB_TARGET} variables to \c{TRUE}. + +\sa {qt6_android_generate_deployment_settings}{qt_android_generate_deployment_settings()}, + {qt6_finalize_target}{qt_finalize_target()}, + {qt6_finalize_project}{qt_finalize_project()} + +\section1 Example + +\snippet cmake-macros/examples.cmake qt_android_deploy_basic + +The above commands define the \c{myapp_make_apk}, \c{myapp_make_aab}, \c{apk}, +and \c{aab} build targets which can be used to generate just the +\c{myapp} packages or all APKs and AABs in the project respectively. +*/ diff --git a/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc new file mode 100644 index 0000000000..a29e1f6123 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_android_apply_arch_suffix.qdoc @@ -0,0 +1,36 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-android-apply-arch-suffix.html +\ingroup cmake-commands-qtcore + +\title qt_android_apply_arch_suffix +\keyword qt6_android_apply_arch_suffix + +\summary {Configures the target binary's name to include an architecture-specific suffix.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable +or \l qt_add_library instead. +\cmakecommandandroidonly + +\section1 Synopsis + +\badcode +qt_android_apply_arch_suffix(target) +\endcode + +\versionlessCMakeCommandsNote qt6_android_apply_arch_suffix() + +\section1 Description + +The CMake \c{SUFFIX} target property controls the suffix used on the file name +of the target's built binary. This command is a convenience for setting that +property to an architecture-specific value. This is useful when installing +multiple builds for different Android architectures into the same install +location, as it prevents the libraries for different architectures from +overwriting each other. +*/ 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 new file mode 100644 index 0000000000..5a7bbdc33f --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_android_generate_deployment_settings.qdoc @@ -0,0 +1,82 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-android-generate-deployment-settings.html +\ingroup cmake-commands-qtcore + +\title qt_android_generate_deployment_settings +\keyword qt6_android_generate_deployment_settings + +\summary {Generates the deployment settings file needed by androiddeployqt.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.0 +\warning This command is deprecated since Qt 6.5. Use \l qt_add_executable instead. +\cmakecommandandroidonly + +\section1 Synopsis + +\badcode +qt_android_generate_deployment_settings(target) +\endcode + +\versionlessCMakeCommandsNote qt6_android_generate_deployment_settings() + +\section1 Description + +The \c{androiddeployqt} tool expects a deployment settings file as input. This +command reads CMake variables and properties of the \c{target} to generate such +a file in the target's binary directory. Upon return, the full path to this file +is available in the target's \c{QT_ANDROID_DEPLOYMENT_SETTINGS_FILE} property. + +\section2 CMake Variables + +A number of variables are used while generating the deployment settings file. +Some are provided by Qt, others by CMake or the Android NDK. + +\list +\li \l{cmake-variable-ANDROID_NDK_HOST_SYSTEM_NAME}{ANDROID_NDK_HOST_SYSTEM_NAME} +\li \l{cmake-variable-ANDROID_SDK_ROOT}{ANDROID_SDK_ROOT} +\li \c{CMAKE_ANDROID_ARCH_ABI} +\li \c{CMAKE_ANDROID_NDK} +\li \c{CMAKE_SYSROOT} +\li \l{cmake-variable-QT_ANDROID_APPLICATION_ARGUMENTS}{QT_ANDROID_APPLICATION_ARGUMENTS} +\li \l{cmake-variable-QT_HOST_PATH}{QT_HOST_PATH} +\endlist + +\section2 Target Properties + +The properties below will be read from the specified \c{target}. Note that this +command is called as part of target finalization (see +\l{qt6_finalize_target}{qt_finalize_target()}). If you are using +\l{qt6_add_executable}{qt_add_executable()} to create the target and you need to +modify some of these target properties, you need to ensure that target +finalization is deferred. See \l{qt6_add_executable}{qt_add_executable()} for +how to accomplish this. + +\list +\li \l{cmake-target-property-QT_ANDROID_DEPLOYMENT_DEPENDENCIES}{QT_ANDROID_DEPLOYMENT_DEPENDENCIES} +\li \l{cmake-target-property-QT_ANDROID_EXTRA_LIBS}{QT_ANDROID_EXTRA_LIBS} +\li \l{cmake-target-property-QT_ANDROID_EXTRA_PLUGINS}{QT_ANDROID_EXTRA_PLUGINS} +\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_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} +\li \l{cmake-target-property-QT_QML_ROOT_PATH}{QT_QML_ROOT_PATH} +\li \l{cmake-target-property-qt_no_entrypoint}{qt_no_entrypoint} +\endlist + +Upon return, the \c{QT_ANDROID_DEPLOYMENT_SETTINGS_FILE} target property will +contain the location of the generated deployment settings file. + +\sa {qt6_android_add_apk_target}{qt_android_add_apk_target()}, + {qt6_finalize_target}{qt_finalize_target()} + +\section1 Example + +\snippet cmake-macros/examples.cmake qt_android_deploy_basic +*/ diff --git a/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc new file mode 100644 index 0000000000..45fd8f4c5f --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_qt_conf.qdoc @@ -0,0 +1,78 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-qt-conf.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_qt_conf +\keyword qt6_deploy_qt_conf + +\summary {Write a qt.conf file at deployment time.} + +\include cmake-find-package-core.qdocinc + +Unlike most other CMake commands provided by Qt, \c{qt_deploy_qt_conf()} can +only be called from a deployment script. It cannot be called directly by the +project. + +\cmakecommandsince 6.3 +\note This command does not usually need to be called directly. It is used + internally by other higher level commands, but projects wishing to + implement more customized deployment logic may find it useful. + +\section1 Synopsis + +\badcode +qt_deploy_qt_conf(file_path + [PREFIX prefix] + [DOC_DIR doc_dir] + [HEADERS_DIR headers_dir] + [LIB_DIR lib_dir] + [LIBEXEC_DIR libexec_dir] + [BIN_DIR bin_dir] + [PLUGINS_DIR plugins_dir] + [QML_DIR qml_dir] + [ARCHDATA_DIR archdata_dir] + [DATA_DIR data_dir] + [TRANSLATIONS_DIR translations_dir] + [EXAMPLES_DIR examples_dir] + [TESTS_DIR test_dir] + [SETTINGS_DIR settings_dir] +) +\endcode + +\section1 Description + +Use this command when you need to generate a \l{Using qt.conf}{qt.conf} file +during deployment. The default value of any path supported by \c{qt.conf} can +be overridden with the corresponding \c{..._DIR} option. The command will only +write a path to the generated \c{qt.conf} file if it differs from the default +value. +The default values can be found at \l{Overriding Paths}. + +The \c file_path argument expects an absolute path to the location where the +\c qt.conf file should be written to. The \l{QT_DEPLOY_PREFIX} and \l{QT_DEPLOY_BIN_DIR} +variables can be used to dynamically specify a path relative to the deployment binary directory, +as shown in the example below. This helps avoid hard-coding an absolute path. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + {qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()} + +\section1 Example + +\badcode +# The following script must only be executed at install time +qt_generate_deploy_script( + OUTPUT_SCRIPT deploy_script + CONTENT " +qt_deploy_qt_conf(\"\${QT_DEPLOY_PREFIX}/\${QT_DEPLOY_BIN_DIR}/qt.conf\" + DATA_DIR \"./custom_data_dir\" + TRANSLATIONS_DIR \"./custom_translations_dir\" +) +") + +install(SCRIPT ${deploy_script}) +\endcode + +*/ diff --git a/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc new file mode 100644 index 0000000000..f64960492a --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_runtime_dependencies.qdoc @@ -0,0 +1,198 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-runtime-dependencies.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_runtime_dependencies +\keyword qt6_deploy_runtime_dependencies + +\summary {Deploy Qt plugins, Qt and non-Qt libraries needed by an executable.} + +\include cmake-find-package-core.qdocinc + +Unlike most other CMake commands provided by Qt, \c{qt_deploy_runtime_dependencies()} +can only be called from a deployment script. It cannot be called directly by the +project during the configure stage. + +\cmakecommandsince 6.3 +\note This command does not usually need to be called directly. It is used + internally by other higher level commands, but projects wishing to + implement more customized deployment logic may find it useful. + +\section1 Synopsis + +\badcode +qt_deploy_runtime_dependencies( + EXECUTABLE executable + [ADDITIONAL_EXECUTABLES files...] + [ADDITIONAL_LIBRARIES files...] + [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] + [VERBOSE] + [NO_OVERWRITE] + [NO_APP_STORE_COMPLIANCE] + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [DEPLOY_TOOL_OPTIONS] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] +) +\endcode + +\section1 Description + +When installing an application, it may be desirable to also install the +libraries and plugins it depends on. When the application is a macOS app bundle +or a Windows executable, \c{qt_deploy_runtime_dependencies()} can be called +from an install-time script to deploy those dependencies. It will install +non-system Qt libraries plus an appropriate set of Qt plugins. + +On Linux, the command will deploy additional libraries, beyond just those +related to Qt, that are included with the project. However, when executed on +macOS or Windows, the command will use either \c macdeployqt or \c windeployqt, +which will only deploy libraries that are specific to Qt. + +This command only considers runtime dependencies for which linking +relationships exist in the underlying binaries. It does not deploy QML modules, +see \l{qt6_deploy_qml_imports}{qt_deploy_qml_imports()} for that. + +\section1 Arguments + +The \c{EXECUTABLE} option must be provided. + +The \c{executable} argument should be the path to the executable file in the +build directory. For example, \c{${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe}, or more +dynamically \c{$<TARGET_FILE:MyApp>}. Specifying raw target names not wrapped in +a generator expression like \c{<TARGET_FILE:>} is not supported. + +For macOS app bundles, the \c{executable} argument should be a path to the +bundle directory, relative to the base install location. +For example \c{MyApp.app}, or more dynamically +\c{$<TARGET_FILE_NAME:MyApp>.app}. +Specifying raw target names not wrapped in a generator epxression like +\c{<TARGET_FILE_NAME:>} is not supported. + +It may also be desirable to install dependencies for other binaries related to +the \c{executable}. For example, plugins provided by the project might have +further dependencies, but because those plugins won't be linked directly to the +executable, \c{qt_deploy_runtime_dependencies()} won't automatically discover +them. The \c{ADDITIONAL_EXECUTABLES}, \c{ADDITIONAL_LIBRARIES}, and +\c{ADDITIONAL_MODULES} options can be used to specify additional binaries +whose dependencies should also be deployed (installing the named binaries +themselves is still the project's responsibility). The naming of these keywords +follows CMake's conventions, so Qt plugins would be specified using +\c{ADDITIONAL_MODULES}. +Each value should be a path relative to the base install location. The values +can use generator expressions, same as with the \c{EXECUTABLE} option. +Specifying raw target names not wrapped in a generator epxression like +\c{<TARGET_FILE_NAME:>} is not supported. + +When installing a Windows application, it is common to need a +\l{Using qt.conf}{qt.conf} file when following CMake's default install +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 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} +variable can be set in the project before the first \c{find_package(Qt6)} call +to make deployment output verbose by default. + +The \c{qt_deploy_runtime_dependencies()} command overwrites existing files by +default (some warnings may still be issued). Use the \c{NO_OVERWRITE} option +to prevent overwriting existing files. Note that this option currently only +affects macOS and Windows deployments. + +By default, if \c{executable} is a macOS app bundle, only Qt plugins and Qt +libraries that comply with Apple's app store requirements are deployed. The +\c{NO_APP_STORE_COMPLIANCE} option can be given to disable that constraint. + +On platforms other than macOS, Qt translations are automatically deployed. To +inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use +\l{qt6_deploy_translations}{qt_deploy_translations()} to deploy translations +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}, +\c{POST_INCLUDE_FILES}, and \c{POST_EXCLUDE_FILES} are only meaningful in this +context and are forwarded unaltered to \c{file(GET_RUNTIME_DEPENDENCIES)}. See +the documentation of that command for details. + +On Linux, runtime dependencies that are located in system library directories +are not deployed by default. If \c{POST_EXCLUDE_REGEXES} is specified, this +automatic exclusion is not performed. + +The default value of \c{POST_EXCLUDE_REGEXES} is constructed from the value of +\l{QT_DEPLOY_IGNORED_LIB_DIRS}. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + {qt6_deploy_qt_conf}{qt_deploy_qt_conf()}, + {qt6_deploy_qml_imports}{qt_deploy_qml_imports()} + +\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_deploy_translations.qdoc b/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc new file mode 100644 index 0000000000..43ff23a35a --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc @@ -0,0 +1,76 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-deploy-translations.html +\ingroup cmake-commands-qtcore + +\title qt_deploy_translations +\keyword qt6_deploy_translations + +\summary {Deploy Qt translations needed by an executable.} + +\include cmake-find-package-core.qdocinc + +Unlike most other CMake commands provided by Qt, \c{qt_deploy_translations()} +can only be called from a deployment script. It cannot be called directly by the +project during the configure stage. + +\cmakecommandsince 6.5 +\preliminarycmakecommand +\note This command does not usually need to be called directly. It is used + internally by other higher level commands, but projects wishing to + implement more customized deployment logic may find it useful. + +\section1 Synopsis + +\badcode +qt_deploy_translations( + [CATALOGS catalogs] + [LOCALES locales] + [LCONVERT lconvert_executable] + [VERBOSE] +) +\endcode + +\section1 Description + +When installing an application, it may be desirable to also install the +translations that belong to the used Qt modules. The \c qt_deploy_translations +command collects the necessary \c{.qm} file from the Qt installation and +compiles them into one \c{qt_${language}.qm} file per language. The \c{.qm} +files are installed into \c{QT_DEPLOY_TRANSLATIONS_DIR}. + +\section1 Arguments + +The \c LOCALES argument specifies for which locales translations should be +deployed. This is a list of language/region combinations as described in +\l{Changing the Target Locale}{Qt Linguist's manual for translators}. Examples +for valid locales are: \c{de}, \c{pl}, or \c{pt_BR}. + +If \c LOCALES is omitted, then all available locales are deployed. + +The \c CATALOGS argument specifies a list of \l{Available +Catalogs}{translation catalogs} to be deployed. If this argument is +omitted, then all catalogs are deployed that belong to any Qt module +that is used in the project via \c{find_package}. + +The \c LCONVERT argument specifies the \c lconvert executable that is used to +combine the catalogs. By default, the Qt installation's \c lconvert is used. + +For debugging purposes, the \c VERBOSE argument can be set to turn on diagnostic +messages. + +\sa QT_DEPLOY_TRANSLATIONS_DIR + +\section1 Example + +The following example deploys Danish and German translations of the Qt +libraries. + +\badcode +qt_deploy_translations( + LOCALES da de +) +\endcode +*/ diff --git a/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc new file mode 100644 index 0000000000..91de52544e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_disable_unicode_defines.qdoc @@ -0,0 +1,34 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-disable-unicode-defines.html +\ingroup cmake-commands-qtcore + +\title qt_disable_unicode_defines +\keyword qt6_disable_unicode_defines + +\summary {Prevents some unicode-related compiler definitions being set automatically on a target.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_disable_unicode_defines(target) +\endcode + +\versionlessCMakeCommandsNote qt6_disable_unicode_defines() + +\section1 Description + +In Qt 6, the \c UNICODE and \c{_UNICODE} compiler definitions are set by +default for targets that link against Qt modules. This is in line with the +qmake behavior, but it is a change compared to the CMake API behavior in Qt 5. +Calling \c{qt_disable_unicode_defines()} on a \c target prevents these compiler +definitions from being automatically set. + +\sa {qt6_allow_non_utf8_sources}{qt_allow_non_utf8_sources()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc new file mode 100644 index 0000000000..7ec8d90f9b --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_extract_metatypes.qdoc @@ -0,0 +1,69 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-extract-metatypes.html +\ingroup cmake-commands-qtcore + +\title qt_extract_metatypes +\keyword qt6_extract_metatypes + +\summary {Extracts metatypes from a Qt target and generates an associated metatypes.json file.} + +\cmakecommandsince 6.0 +\preliminarycmakecommand + +\section1 Synopsis + +\badcode +qt_extract_metatypes(target + [MANUAL_MOC_JSON_FILES json_files...] + [OUTPUT_FILES variable_name] +) +\endcode + +\versionlessCMakeCommandsNote qt6_extract_metatypes() + +\section1 Description + +Certain operations rely on metatype information being generated and collected +on targets. This is typically handled internally by Qt commands, but for +scenarios where this is not the case, \c{qt_extract_metatypes()} can be called +to force the collection of this information for a specific \c target. + +Metatype information is generated for a target's source files in one of the +following ways: + +\list +\li Automatically by AUTOMOC. The \c{qt_extract_metatypes()} command detects + when AUTOMOC is enabled on the \c target and will automatically extract the + information it needs. +\li Manually by invoking \c moc with the \c{--output-json} option. The project + is responsible for keeping track of all the JSON files generated using this + method and passing them to \c{qt_extract_metatypes()} with the + \c MANUAL_MOC_JSON_FILES option. +\endlist + +\c{qt_extract_metatypes()} produces a target-specific metatypes JSON file which +collects all the metatype details from the AUTOMOC and manual moc inputs. +It does this by calling \c moc with the \c{--collect-json} option. +If you need to know where to find the resultant metatypes JSON file (for +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_finalize_project.qdoc b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc new file mode 100644 index 0000000000..5506712691 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_finalize_project.qdoc @@ -0,0 +1,53 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-finalize-project.html +\ingroup cmake-commands-qtcore + +\title qt_finalize_project +\keyword qt6_finalize_project + +\summary {Handles various common platform-specific tasks associated with a Qt project.} +\preliminarycmakecommand + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_finalize_project() +\endcode + +\versionlessCMakeCommandsNote qt6_finalize_project() + +\section1 Description + +Some targets that are created using Qt commands require additional actions +at the end of CMake configuring phase. +Depending on the platform, the function typically: +\list + \li Walks the build tree. + \li Resolves dependencies. + \li Applies any extra deployment steps. +\endlist + +With CMake version 3.19 or later, you don't need to call this command since +it consists of sub-commands that are ordinarily invoked at the end of +\c CMAKE_SOURCE_DIR directory scope processing. + +\include cmake-android-qt-finalize-project-warning.qdocinc warning + +\section2 Examples + +For projects that use a CMake version lower than 3.19, you need to call +\c qt_finalize_project manually. This example shows the typical use of the +function: + +\snippet cmake-macros/examples.cmake qt_finalize_project_manual + +\sa {cmake-variable-QT_NO_COLLECT_BUILD_TREE_APK_DEPS}{QT_NO_COLLECT_BUILD_TREE_APK_DEPS} +\sa {cmake-variable-QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS}{QT_NO_COLLECT_IMPORTED_TARGET_APK_DEPS} +*/ diff --git a/src/corelib/doc/src/cmake/qt_finalize_target.qdoc b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc new file mode 100644 index 0000000000..b74dee64d2 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_finalize_target.qdoc @@ -0,0 +1,89 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-finalize-target.html +\ingroup cmake-commands-qtcore + +\title qt_finalize_target +\keyword qt6_finalize_target + +\summary {Handles various common platform-specific tasks associated with Qt targets.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.2 + +\section1 Synopsis + +\badcode +qt_finalize_target(target) +\endcode + +\versionlessCMakeCommandsNote qt6_finalize_target() + +\section1 Description + +After a target is created, further processing or \e{finalization} steps are +sometimes needed. The steps to perform depend on the platform, the type of +target, and on various properties of the target. These steps are expected to be +performed within the same directory scope as the one in which the \c{target} +was created, so this command should also be called from that same directory +scope. + +This command is ordinarily invoked as part of a call to +\l{qt6_add_executable}{qt_add_executable()}, +\l{qt6_add_library}{qt_add_library()}, or \l{qt6_add_plugin}{qt_add_plugin()}. +The timing of when that call takes place and when a project might need to call +it explicitly, is discussed in the documentation of those commands. + +\sa {qt6_set_finalizer_mode}{qt_set_finalizer_mode()} + +\section1 Executable Targets + +For executable targets, \c{qt_finalize_target()} implements the logic described +in the subsections below, as appropriate for the platform and target provided. +Later Qt releases may expand finalization processing further. + +\section2 All Platforms + +Some internal processing is performed to facilitate automatic linking of Qt +plugins. This is especially important if using a statically built Qt or a +CMake version earlier than 3.21. + +\section2 Android + +\list +\li Generate a deployment settings file for the \c target. +\li Create a build target for generating an APK. +\endlist + +\section2 WASM + +Create \c{${target}.html} (a target-specific \c{wasm_shell.html} file), +\c{qtloader.js}, and \c{qtlogo.svg} files in the \c{CMAKE_CURRENT_BINARY_DIR}. + +\section2 iOS + +Finalization attempts to provide sensible values for the following target +properties if they are not already set, and their corresponding \c{CMAKE_...} +variable is also not set: + +\list +\li \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM +\li \c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER +\li \c MACOSX_BUNDLE_GUI_IDENTIFIER +\endlist + +If required, the \l QT_NO_SET_XCODE_DEVELOPMENT_TEAM_ID variable can be used to +disable setting \c XCODE_ATTRIBUTE_DEVELOPMENT_TEAM, and the +\l QT_NO_SET_XCODE_BUNDLE_IDENTIFIER variable can be used to disable setting +\c XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER and \c MACOSX_BUNDLE_GUI_IDENTIFIER. + +\section1 Library Targets + +As of this Qt version, finalization for library targets does not perform any +processing. Future Qt versions may add finalization processing for libraries, +so you should ensure finalization is still invoked in the expected way. + +*/ 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 new file mode 100644 index 0000000000..31d9e4384b --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_app_script.qdoc @@ -0,0 +1,110 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-app-script.html +\ingroup cmake-commands-qtcore + +\title qt_generate_deploy_app_script +\keyword qt6_generate_deploy_app_script + +\summary {Generate a deployment script for an application.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 +\note This command is currently only supported on Windows, macOS, and Linux. + +\section1 Synopsis + +\badcode +qt_generate_deploy_app_script( + TARGET target + OUTPUT_SCRIPT <var> + [NO_TRANSLATIONS] + [NO_COMPILER_RUNTIME] + [NO_UNSUPPORTED_PLATFORM_ERROR] + [DEPLOY_TOOL_OPTIONS ...] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] +) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_deploy_app_script() + +\section1 Description + +Installing an executable target with \l{install(TARGETS)} only installs the +target's executable (except for macOS app bundles, which will copy the whole +bundle). You need to explicitly install any other libraries or plugins the +executable depends on yourself. \c{qt_generate_deploy_app_script()} is a +convenience command intended to simplify that process. It expects the +application to follow Qt's recommended install directory structure fairly +closely. That structure is based on CMake's default install layout, as +determined by \l{GNUInstallDirs} (except for macOS app bundles, which follow +Apple's requirements instead). + +The command generates a script whose name will be stored in the variable named +by the \c{OUTPUT_SCRIPT} option. That script is only written at CMake +generation time. It is intended to be used with the \l{install(SCRIPT)} command, +which should come after the application's target has been installed using +\l{install(TARGETS)}. + +The deployment script will call \l{qt6_deploy_runtime_dependencies} +{qt_deploy_runtime_dependencies()} with a suitable set of options for the standard +install layout. Currently, this is only implemented for +\list + \li macOS app bundles built on a macOS host, + \li Linux executables built on a Linux host, + \li and Windows executables built on a Windows host. +\endlist +Cross-building a Windows executable on a Linux host, as well as similar +scenarios, are not currently supported. +Calling \c{qt_generate_deploy_app_script()} in such a case will result +in a fatal error, unless the \c{NO_UNSUPPORTED_PLATFORM_ERROR} option is given. + +On platforms other than macOS, Qt translations are automatically deployed. To +inhibit this behavior, specify \c{NO_TRANSLATIONS}. Use +\l{qt6_deploy_translations}{qt_deploy_translations()} to deploy translations 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. + +For deploying a QML application, use +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} +instead. + +For generating a custom deployment script, use +\l{qt6_generate_deploy_script}{qt_generate_deploy_script}. + +The options \c{PRE_INCLUDE_REGEXES}, \c{PRE_EXCLUDE_REGEXES}, +\c{POST_INCLUDE_REGEXES}, \c{POST_EXCLUDE_REGEXES}, \c{POST_INCLUDE_FILES}, and +\c{POST_EXCLUDE_FILES} can be specified to control the deployment of runtime +dependencies. These options do not apply to all platforms and are forwarded +unmodified to \l{qt6_deploy_runtime_dependencies}{qt_deploy_runtime_dependencies()}. + +\sa {qt6_standard_project_setup}{qt_standard_project_setup()}, + {qt6_generate_deploy_script}{qt_generate_deploy_script()}, + {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} + +\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_generate_deploy_script.qdoc b/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc new file mode 100644 index 0000000000..eb8ed402a9 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_deploy_script.qdoc @@ -0,0 +1,65 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-deploy-script.html +\ingroup cmake-commands-qtcore + +\title qt_generate_deploy_script +\keyword qt6_generate_deploy_script + +\summary {Generate a custom deployment script.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.5 + +\section1 Synopsis + +\badcode +qt_generate_deploy_script( + OUTPUT_SCRIPT <var> + [TARGET target] + [NAME script_name] + [CONTENT content] +) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_deploy_script() + +\section1 Description + +The command generates a script whose full file path will be stored in the +variable named by the \c{OUTPUT_SCRIPT} option. That script is only written +at CMake generation time. It is intended to be used with the \l{install(SCRIPT)} +command, which should come after the application's target has been installed +using \l{install(TARGETS)}. + +The command takes care of generating a file named suitably for multi-config +generators. Necessary includes are added such that Qt's CMake deployment +functions and variables are accessible. + +The \c TARGET argument specifies the target that will be deployed by the script. +This affects the file name of the generated script, unless \c NAME is specified. + +The \c NAME argument controls an identifiable portion within the deployment +script's automatically generated name. The \c NAME argument defaults to \c +custom if neither \c NAME nor \c TARGET are given. + +The \c CONTENT argument specifies the code that is written to the deployment +script. The content may contain generator expressions. + +This command is intended for generating custom deployment scripts that +directly call functions of Qt's deployment API. For less complex +deployment purposes, it is more convenient to use +\l{qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()} or +\l{qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()}. + +\sa {qt6_generate_deploy_app_script}{qt_generate_deploy_app_script()}, + {qt6_generate_deploy_qml_app_script}{qt_generate_deploy_qml_app_script()} + +\section1 Example + +\snippet cmake-macros/deployment.cmake qt_generate_deploy_script_example + +*/ diff --git a/src/corelib/doc/src/cmake/qt_generate_moc.qdoc b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc new file mode 100644 index 0000000000..9b123f9323 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_generate_moc.qdoc @@ -0,0 +1,45 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-generate-moc.html +\ingroup cmake-commands-qtcore + +\title qt_generate_moc +\keyword qt6_generate_moc + +\summary {Calls moc on an input file.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.0 + +\section1 Synopsis + +\badcode +qt_generate_moc(src_file dest_file + [TARGET target]) +\endcode + +\versionlessCMakeCommandsNote qt6_generate_moc() + +\section1 Description + +Creates a rule to call the \l{moc}{Meta-Object Compiler (moc)} on \c src_file +and store the output in \c dest_file. + +\note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a +more convenient way to let source files be processed with \c{moc}. +\l qt_wrap_cpp is also similar, but automatically generates a temporary file +path for you. + +\section1 Arguments + +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}. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_generate_moc +*/ diff --git a/src/corelib/doc/src/cmake/qt_import_plugins.qdoc b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc new file mode 100644 index 0000000000..1f81a21cd2 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_import_plugins.qdoc @@ -0,0 +1,97 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-import-plugins.html +\ingroup cmake-commands-qtcore + +\title qt_import_plugins +\keyword qt6_import_plugins + +\summary {Specifies a custom set of plugins to import or exclude.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.14 + +\section1 Synopsis + +\badcode +qt_import_plugins(target + [INCLUDE plugin ...] + [EXCLUDE plugin ...] + [INCLUDE_BY_TYPE plugin_type plugin ...] + [EXCLUDE_BY_TYPE plugin_type] + [NO_DEFAULT] +) +\endcode + +\versionlessCMakeCommandsNote qt6_import_plugins() + +\section1 Description + +Specifies a custom set of plugins to import. The optional arguments: +\c INCLUDE, \c EXCLUDE, \c INCLUDE_BY_TYPE, and \c EXCLUDE_BY_TYPE, +can be used more than once. + +\list +\li \c INCLUDE -- can be used to specify a list of plugins to import. +\li \c EXCLUDE -- can be used to specify a list of plugins to exclude. +\li \c INCLUDE_BY_TYPE -- can be used to override the list of plugins to + import for a certain plugin type. +\li \c EXCLUDE_BY_TYPE -- can be used to specify a plugin type to exclude; + then no plugins of that type are imported. +\li \c NO_DEFAULT -- prevent the default plugins from being included + automatically (for example, the default platform plugin). +\endlist + +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 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 static plugin. Consequently, any target that links against +a plugin has this C++ file added to its \c SOURCES. + +\section1 Examples + +\snippet cmake-macros/examples.cmake qt_import_plugins + +In the snippet above, the following occurs with the executable \c myapp: + +\list +\li The \c Qt6::QCocoaIntegrationPlugin is imported into myapp. +\li The \c Qt6::QMinimalIntegrationPlugin plugin is + excluded from being automatically imported into myapp. +\li The default list of plugins for \c imageformats is + overridden to only include Qt6::QGifPlugin and Qt6::QJpegPlugin. +\li All \c sqldrivers plugins are excluded from automatic importing. +\endlist + +\sa{qt6_import_qml_plugins}{qt_import_qml_plugins()} +*/ diff --git a/src/corelib/doc/src/cmake/qt_policy.qdoc b/src/corelib/doc/src/cmake/qt_policy.qdoc new file mode 100644 index 0000000000..6deb7a729c --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_policy.qdoc @@ -0,0 +1,65 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-policy.html +\ingroup cmake-commands-qtcore + +\title qt_policy +\keyword qt6_policy + +\summary {Modify the default behavior of Qt's CMake API.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.5 + +\section1 Synopsis + +\badcode +qt_policy( + [SET <policy_name> behavior] + [GET <policy_name> <variable>] +) +\endcode + +\versionlessCMakeCommandsNote qt6_policy() + +\section1 Description + +This command has two modes: + +\list +\li When the \c{SET} keyword is used, this command can be used to opt in to + behavior changes in Qt's CMake API, or to explicitly opt out of them. +\li When the \c{GET} keyword is used, \c{<variable>} is set to the current + behavior for the policy, i.e. \c OLD or \c NEW. +\endlist + +\c{<policy_name>} must be the name of one of the \l{Qt CMake policies}. +Policy names have the form of \c{QTP<NNNN>} where <NNNN> is +an integer specifying the index of the policy. Using an invalid policy +name results in an error. + +Code supporting older Qt versions can check the existence of a policy by +checking the value of the \c{QT_KNOWN_POLICY_<policy_name>} variable before +getting the value of \c <policy_name> or setting its behavior. + +\badcode +if(QT_KNOWN_POLICY_<policy_name>) + qt_policy(SET <policy_name> NEW) +endif() +\endcode + +You can set \c behavior to one of the following options: + +\list +\li \c{NEW} to opt into the new behavior +\li \c{OLD} to explicitly opt-out of it +\endlist + +\qtpolicydeprecatedbehavior + +\sa qt_standard_project_setup + +*/ diff --git a/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc new file mode 100644 index 0000000000..28622c11e8 --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_set_finalizer_mode.qdoc @@ -0,0 +1,90 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-set-finalizer-mode.html +\ingroup cmake-commands-qtcore + +\title qt_set_finalizer_mode +\keyword qt6_set_finalizer_mode + +\summary {Customizes aspects of a target's finalization.} + +\cmakecommandsince 6.2 +\preliminarycmakecommand + +\section1 Synopsis + +\badcode +qt_set_finalizer_mode(target + ENABLE | DISABLE + MODES modes... +) +\endcode + +\versionlessCMakeCommandsNote qt6_set_finalizer_mode() + +\section1 Description + +This command is used to customize some aspects of the finalization of a +specific \c target. It only has an effect if called before \c target is +finalized, which occurs in one of the following scenarios: + +\list +\li The project explicitly calls \l{qt6_finalize_target}{qt_finalize_target()} + for the \c target. This usually means the \c MANUAL_FINALIZATION keyword was + passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target + was defined. +\li CMake 3.17 or earlier is being used, in which case finalization always + occurs immediately as part of the call to + \l{qt6_add_executable}{qt_add_executable()}. +\li CMake 3.18 or later is being used, the \c MANUAL_FINALIZATION keyword was + not passed to \l{qt6_add_executable}{qt_add_executable()} when the \c target + was defined, and deferred finalization has been completed at the end of the + \c target's directory scope. +\endlist + +\c{qt_set_finalizer_mode()} is used to enable or disable a list of \e modes, +where a mode corresponds to a specific aspect of finalization. The currently +supported finalization modes are: + +\table +\header + \li Mode + \li Default + \li Finalization behavior +\row + \li \c static_plugins + \li Enabled + \li When Qt is built statically, it creates initializer object libraries + for its static plugins. If \c target is an executable and this + finalization mode is enabled, any plugin initializer object libraries + needed by the \c target will be directly linked to it. This + prevents cycles between Qt-provided static libraries and may reduce + link time. When this finalizer mode is disabled, each plugin + initializer is instead propagated via usage requirements of its + associated Qt library, which may cause cycles. If Qt is not built + statically, this finalizer mode is not relevant and isn't used. +\endtable + +\sa {qt6_finalize_target}{qt_finalize_target()} + +\section1 Example + +The following example assumes you are using CMake 3.19 or later (required for +deferred finalization): + +\badcode +qt_add_executable(my_app main.cpp) +qt_set_finalizer_mode(my_app ENABLE MODES static_plugins) +\endcode + +The same example using manual finalization might look like this: + +\badcode +qt_add_executable(my_app MANUAL_FINALIZATION main.cpp) +qt_set_finalizer_mode(my_app ENABLE MODES static_plugins) +qt_finalize_target(my_app) +\endcode + +*/ diff --git a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc new file mode 100644 index 0000000000..59b33f599c --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc @@ -0,0 +1,101 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-standard-project-setup.html +\ingroup cmake-commands-qtcore + +\title qt_standard_project_setup +\keyword qt6_standard_project_setup + +\summary {Setup project-wide defaults to a standard arrangement.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 6.3 + +\section1 Synopsis + +\badcode +qt_standard_project_setup( + [REQUIRES <version>] + [SUPPORTS_UP_TO <version>] + [I18N_TRANSLATED_LANGUAGES <language...>] + [I18N_SOURCE_LANGUAGE <language>] +) +\endcode + +\versionlessCMakeCommandsNote qt6_standard_project_setup() + +\section1 Description + +This command simplifies the task of setting up a typical Qt application. +It would usually be called immediately after the first \c{find_package(Qt6)} +call, normally in the top level \c{CMakeLists.txt} file and before any targets +have been defined. It does the following things: + +\list +\li The standard CMake variables \c{CMAKE_AUTOMOC} and \c{CMAKE_AUTOUIC} + are set to true if they are not already defined. + This enables all Qt-related autogen features by default for subsequently + created targets in the current directory scope and below. +\li CMake's \l{GNUInstallDirs} module is automatically included. This defines + appropriate defaults for variables like \c{CMAKE_INSTALL_BINDIR}, + \c{CMAKE_INSTALL_LIBDIR}, and so on. +\li When targeting Windows, if the \c{CMAKE_RUNTIME_OUTPUT_DIRECTORY} variable + is not already set, it will be set to + \c{${CMAKE_CURRENT_BINARY_DIR}}. +\li When target platforms other than Apple or Windows, \c{CMAKE_INSTALL_RPATH} + will be augmented as described below. +\li CMake's \l USE_FOLDERS property is set to \c{ON}, and \l QT_TARGETS_FOLDER is + set to \c{QtInternalTargets}. IDEs that support folders will display + Qt-internal targets in this folder. +\endlist + +Since Qt 6.5, it is possible to change the default behavior of Qt's CMake +API by opting in to changes from newer Qt versions. If \c{REQUIRES} is +specified, all suggested changes introduced in Qt up to \c{REQUIRES} are enabled, +and using an older Qt version will result in an error. +If additionally \c{SUPPORTS_UP_TO} has been specified, any new changes introduced +in versions up to \c{SUPPORTS_UP_TO} are also enabled (but using an older Qt +version is not an error). This is similar to CMake's policy concept +(compare \l{cmake_policy}). + +On platforms that support \c{RPATH} (other than Apple platforms), two values +are appended to the \c{CMAKE_INSTALL_RPATH} variable by this command. +\c{$ORIGIN} is appended so that libraries will find other libraries they depend +on in the same directory as themselves. \c{$ORIGIN/<reldir>} is also appended, +where \c{<reldir>} is the relative path from \c{CMAKE_INSTALL_BINDIR} to +\c{CMAKE_INSTALL_LIBDIR}. This allows executables installed to +\c{CMAKE_INSTALL_BINDIR} to find any libraries they may depend on installed to +\c{CMAKE_INSTALL_LIBDIR}. Any duplicates in \c{CMAKE_INSTALL_RPATH} are +removed. In practice, these two values ensure that executables and libraries +will find their link-time dependencies, assuming projects install them to the +default locations the \l{install(TARGETS)} command uses when no destination is +explicitly provided. + +To disable folder support for IDEs, set \l USE_FOLDERS to \c OFF before or after +the call to \c{qt_standard_project_setup}. + +The \c{qt_standard_project_setup()} command can effectively be disabled by +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 new file mode 100644 index 0000000000..3b298a9d7e --- /dev/null +++ b/src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc @@ -0,0 +1,90 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qt-wrap-cpp.html +\ingroup cmake-commands-qtcore + +\title qt_wrap_cpp +\keyword qt6_wrap_cpp + +\summary {Creates .moc files from sources.} + +\include cmake-find-package-core.qdocinc + +\cmakecommandsince 5.0 + +\section1 Synopsis + +\badcode +qt_wrap_cpp(<VAR> src_file1 [src_file2 ...] + [TARGET target] + [OPTIONS ...] + [DEPENDS ...]) +\endcode + +\versionlessCMakeCommandsNote qt6_wrap_cpp() + +\section1 Description + +Creates rules for calling the \l{moc}{Meta-Object Compiler (moc)} on the given +source files. For each input file, an output file is generated in the build +directory. The paths of the generated files are added to \c{<VAR>}. + +\note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a +more convenient way to let source files be processed with \c{moc}. + +\section1 Arguments + +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 +Q_PLUGIN_METADATA() macro. + +\section1 Examples + +\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 5b9b700669..847be1bff6 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page containers.html @@ -56,19 +32,15 @@ in situations where they are used as read-only containers by all threads used to access them. - For traversing the items stored in a container, you can use one - of two types of iterators: \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are easier to - use and provide high-level functionality, whereas the STL-style - iterators are slightly more efficient and can be used together - with Qt's and STL's \l{generic algorithms}. - - Qt also offers a \l{foreach} keyword that make it very - easy to iterate over all the items stored in a container. + The containers provide iterators for traversal. \l{STL-style iterators} + are the most efficient ones and can be used together with Qt's and + STL's \l{generic algorithms}. + \l{Java-style Iterators} are provided for backwards compatibility. \note Since Qt 5.14, range constructors are available for most of the container classes. QMultiMap is a notable exception. Their use is - encouraged in place of the various from/to methods. For example: + encouraged to replace of the various deprecated from/to methods of Qt 5. + For example: \snippet code/doc_src_containers.cpp 25 @@ -220,182 +192,39 @@ the C++ language doesn't specify any initialization; in those cases, Qt's containers automatically initialize the value to 0. - \section1 The Iterator Classes - - Iterators provide a uniform means to access items in a container. - Qt's container classes provide two types of iterators: Java-style - iterators and STL-style iterators. Iterators of both types are - invalidated when the data in the container is modified or detached - from \l{Implicit Sharing}{implicitly shared copies} due to a call - to a non-const member function. - - \section2 Java-Style Iterators - - The Java-style iterators are new in Qt 4 and are the standard - ones used in Qt applications. They are more convenient to use than - the STL-style iterators, at the price of being slightly less - efficient. Their API is modelled on Java's iterator classes. + \section1 Iterating over Containers - For each container class, there are two Java-style iterator data - types: one that provides read-only access and one that provides - read-write access. + \section2 Range-based for - \table - \header \li Containers \li Read-only iterator - \li Read-write iterator - \li QMutableListIterator<T> - \row \li QList<T>, QQueue<T>, QStack<T>, \li QListIterator<T> - \li QMutableListIterator<T> - \row \li QSet<T> \li QSetIterator<T> - \li QMutableSetIterator<T> - \row \li QMap<Key, T>, QMultiMap<Key, T> \li QMapIterator<Key, T> - \li QMutableMapIterator<Key, T> - \row \li QHash<Key, T>, QMultiHash<Key, T> \li QHashIterator<Key, T> - \li QMutableHashIterator<Key, T> - \endtable + Range-based \c for should preferably be used for containers: - In this discussion, we will concentrate on QList and QMap. The - iterator types for QSet have exactly - the same interface as QList's iterators; similarly, the iterator - types for QHash have the same interface as QMap's iterators. - - Unlike STL-style iterators (covered \l{STL-style - iterators}{below}), Java-style iterators point \e between items - rather than directly \e at items. For this reason, they are - either pointing to the very beginning of the container (before - the first item), at the very end of the container (after the last - item), or between two items. The diagram below shows the valid - iterator positions as red arrows for a list containing four - items: - - \image javaiterators1.png - - Here's a typical loop for iterating through all the elements of a - QList<QString> in order and printing them to the console: - - \snippet code/doc_src_containers.cpp 1 - - It works as follows: The QList to iterate over is passed to the - QListIterator constructor. At that point, the iterator is located - just in front of the first item in the list (before item "A"). - Then we call \l{QListIterator::hasNext()}{hasNext()} to - check whether there is an item after the iterator. If there is, we - call \l{QListIterator::next()}{next()} to jump over that - item. The next() function returns the item that it jumps over. For - a QList<QString>, that item is of type QString. - - Here's how to iterate backward in a QList: - - \snippet code/doc_src_containers.cpp 2 - - The code is symmetric with iterating forward, except that we - start by calling \l{QListIterator::toBack()}{toBack()} - to move the iterator after the last item in the list. - - The diagram below illustrates the effect of calling - \l{QListIterator::next()}{next()} and - \l{QListIterator::previous()}{previous()} on an iterator: - - \image javaiterators2.png - - The following table summarizes the QListIterator API: - - \table - \header \li Function \li Behavior - \row \li \l{QListIterator::toFront()}{toFront()} - \li Moves the iterator to the front of the list (before the first item) - \row \li \l{QListIterator::toBack()}{toBack()} - \li Moves the iterator to the back of the list (after the last item) - \row \li \l{QListIterator::hasNext()}{hasNext()} - \li Returns \c true if the iterator isn't at the back of the list - \row \li \l{QListIterator::next()}{next()} - \li Returns the next item and advances the iterator by one position - \row \li \l{QListIterator::peekNext()}{peekNext()} - \li Returns the next item without moving the iterator - \row \li \l{QListIterator::hasPrevious()}{hasPrevious()} - \li Returns \c true if the iterator isn't at the front of the list - \row \li \l{QListIterator::previous()}{previous()} - \li Returns the previous item and moves the iterator back by one position - \row \li \l{QListIterator::peekPrevious()}{peekPrevious()} - \li Returns the previous item without moving the iterator - \endtable + \snippet code/doc_src_containers.cpp range_for - QListIterator provides no functions to insert or remove items - from the list as we iterate. To accomplish this, you must use - QMutableListIterator. Here's an example where we remove all - odd numbers from a QList<int> using QMutableListIterator: + Note that when using a Qt container in a non-const context, + \l{implicit sharing} may perform an undesired detach of the container. + To prevent this, use \c std::as_const(): - \snippet code/doc_src_containers.cpp 3 + \snippet code/doc_src_containers.cpp range_for_as_const - The next() call in the loop is made every time. It jumps over the - next item in the list. The - \l{QMutableListIterator::remove()}{remove()} function removes the - last item that we jumped over from the list. The call to - \l{QMutableListIterator::remove()}{remove()} does not invalidate - the iterator, so it is safe to continue using it. This works just - as well when iterating backward: + For associative containers, this will loop over the values. - \snippet code/doc_src_containers.cpp 4 + \section2 Index-based - If we just want to modify the value of an existing item, we can - use \l{QMutableListIterator::setValue()}{setValue()}. In the code - below, we replace any value larger than 128 with 128: + For sequential containers that store their items contiguously in memory + (for example, QList), index-based iteration can be used: - \snippet code/doc_src_containers.cpp 5 + \snippet code/doc_src_containers.cpp index - Just like \l{QMutableListIterator::remove()}{remove()}, - \l{QMutableListIterator::setValue()}{setValue()} operates on the - last item that we jumped over. If we iterate forward, this is the - item just before the iterator; if we iterate backward, this is - the item just after the iterator. + \section2 The Iterator Classes - The \l{QMutableListIterator::next()}{next()} function returns a - non-const reference to the item in the list. For simple - operations, we don't even need - \l{QMutableListIterator::setValue()}{setValue()}: - - \snippet code/doc_src_containers.cpp 6 - - As mentioned above QSet's iterator - classes have exactly the same API as QList's. We will now turn to - QMapIterator, which is somewhat different because it iterates on - (key, value) pairs. - - Like QListIterator, QMapIterator provides - \l{QMapIterator::toFront()}{toFront()}, - \l{QMapIterator::toBack()}{toBack()}, - \l{QMapIterator::hasNext()}{hasNext()}, - \l{QMapIterator::next()}{next()}, - \l{QMapIterator::peekNext()}{peekNext()}, - \l{QMapIterator::hasPrevious()}{hasPrevious()}, - \l{QMapIterator::previous()}{previous()}, and - \l{QMapIterator::peekPrevious()}{peekPrevious()}. The key and - value components are extracted by calling \l{QMapIterator::key()}{key()} and \l{QMapIterator::value()}{value()} on - the object returned by next(), peekNext(), previous(), or - peekPrevious(). - - The following example removes all (capital, country) pairs where - the capital's name ends with "City": - - \snippet code/doc_src_containers.cpp 7 - - QMapIterator also provides a \l{QMapIterator::key()}{key()} and a \l{QMapIterator::value()}{value()} function that - operate directly on the iterator and that return the key and - value of the last item that the iterator jumped above. For - example, the following code copies the contents of a QMap into a - QHash: - - \snippet code/doc_src_containers.cpp 8 - - If we want to iterate through all the items with the same - value, we can use \l{QMapIterator::findNext()}{findNext()} - or \l{QMapIterator::findPrevious()}{findPrevious()}. - Here's an example where we remove all the items with a particular - value: - - \snippet code/doc_src_containers.cpp 9 + Iterators provide a uniform means to access items in a container. + Qt's container classes provide two types of iterators: STL-style + iterators and Java-style iterators. Iterators of both types are + invalidated when the data in the container is modified or detached + from \l{Implicit Sharing}{implicitly shared copies} due to a call + to a non-const member function. - \section2 STL-Style Iterators + \section3 STL-Style Iterators STL-style iterators have been available since the release of Qt 2.0. They are compatible with Qt's and STL's \l{generic @@ -438,10 +267,9 @@ \snippet code/doc_src_containers.cpp 10 - Unlike \l{Java-style iterators}, STL-style iterators point - directly at items. The \l{QList::begin()}{begin()} function of a container returns an - iterator that points to the first item in the container. The - \l{QList::end()}{end()} function of a container returns an iterator to the + STL-style iterators point directly at items. The \l{QList::begin()}{begin()} + function of a container returns an iterator that points to the first item in the + container. The \l{QList::end()}{end()} function of a container returns an iterator to the imaginary item one position past the last item in the container. \l {QList::end()}{end()} marks an invalid position; it must never be dereferenced. It is typically used in a loop's break condition. If the list is @@ -458,12 +286,10 @@ In the code snippets so far, we used the unary \c * operator to retrieve the item (of type QString) stored at a certain iterator - position, and we then called QString::toLower() on it. Most C++ - compilers also allow us to write \c{i->toLower()}, but some - don't. + position, and we then called QString::toLower() on it. - For read-only access, you can use const_iterator, \l{QList::constBegin}{constBegin()}, - and \l{QList::constEnd()}{constEnd()}. For example: + For read-only access, you can use const_iterator, \l{QList::cbegin}{cbegin()}, + and \l{QList::cend()}{cend()}. For example: \snippet code/doc_src_containers.cpp 12 @@ -511,7 +337,7 @@ This problem doesn't occur with functions that return a const or non-const reference to a container. - \section3 Implicit sharing iterator problem + \section4 Implicit sharing iterator problem \l{Implicit sharing} has another consequence on STL-style iterators: you should avoid copying a container while @@ -524,83 +350,68 @@ The above example only shows a problem with QList, but the problem exists for all the implicitly shared Qt containers. - \target foreach - \section1 The foreach Keyword - - If you just want to iterate over all the items in a container - in order, you can use Qt's \c foreach keyword. The keyword is a - Qt-specific addition to the C++ language, and is implemented - using the preprocessor. - - Its syntax is: \c foreach (\e variable, \e container) \e - statement. For example, here's how to use \c foreach to iterate - over a QList<QString>: + \section3 Java-Style Iterators + \l{java-style-iterators}{Java-Style iterators} + are modelled + on Java's iterator classes. + New code should prefer \l{STL-Style Iterators}. - \snippet code/doc_src_containers.cpp 15 + \section1 Qt containers compared with std containers - The \c foreach code is significantly shorter than the equivalent - code that uses iterators: + \table + \header \li Qt container \li Closest std container - \snippet code/doc_src_containers.cpp 16 + \row \li \l{QList}<T> + \li Similar to std::vector<T> - Unless the data type contains a comma (e.g., \c{QPair<int, - int>}), the variable used for iteration can be defined within the - \c foreach statement: + \l{QList} and \l{QVector} were unified in Qt 6. Both + use the datamodel from QVector. QVector is now an alias to QList. - \snippet code/doc_src_containers.cpp 17 + This means that QList is not implemented as a linked list, so if + you need constant time insert, delete, append or prepend, + consider \c std::list<T>. See \l{QList} for details. - And like any other C++ loop construct, you can use braces around - the body of a \c foreach loop, and you can use \c break to leave - the loop: + \row \li \l{QVarLengthArray}<T, Prealloc> + \li Resembles a mix of std::array<T> and std::vector<T>. - \snippet code/doc_src_containers.cpp 18 + For performance reasons, QVarLengthArray lives on the stack unless + resized. Resizing it automatically causes it to use the heap instead. - With QMap and QHash, \c foreach accesses the value component of - the (key, value) pairs automatically, so you should not call - values() on the container (it would generate an unnecessary copy, - see below). If you want to iterate over both the keys and the - values, you can use iterators (which are faster), or you can - obtain the keys, and use them to get the values too: + \row \li \l{QStack}<T> + \li Similar to std::stack<T>, inherits from \l{QList}. - \snippet code/doc_src_containers.cpp 19 + \row \li \l{QQueue}<T> + \li Similar to std::queue<T>, inherits from \l{QList}. - For a multi-valued map: + \row \li \l{QSet}<T> + \li Similar to std::unordered_set<T>. Internally, \l{QSet} is implemented with a + \l{QHash}. - \snippet code/doc_src_containers.cpp 20 + \row \li \l{QMap}<Key, T> + \li Similar to std::map<Key, T>. - Qt automatically takes a copy of the container when it enters a - \c foreach loop. If you modify the container as you are - iterating, that won't affect the loop. (If you do not modify the - container, the copy still takes place, but thanks to \l{implicit - sharing} copying a container is very fast.) + \row \li \l{QMultiMap}<Key, T> + \li Similar to std::multimap<Key, T>. - Since foreach creates a copy of the container, using a non-const - reference for the variable does not allow you to modify the original - container. It only affects the copy, which is probably not what you - want. + \row \li \l{QHash}<Key, T> + \li Most similar to std::unordered_map<Key, T>. - An alternative to Qt's \c foreach loop is the range-based \c for that is - part of C++ 11 and newer. However, keep in mind that the range-based - \c for might force a Qt container to \l{Implicit Sharing}{detach}, whereas - \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. + \row \li \l{QMultiHash}<Key, T> + \li Most similar to std::unordered_multimap<Key, T>. - In addition to \c foreach, Qt also provides a \c forever - pseudo-keyword for infinite loops: + \endtable - \snippet code/doc_src_containers.cpp 21 + \section1 Qt containers and std algorithms - If you're worried about namespace pollution, you can disable - these macros by adding the following line to your \c .pro file: + You can use Qt containers with functions from \c{#include <algorithm>}. - \snippet code/doc_src_containers.cpp 22 + \snippet code/doc_src_containers.cpp 26 \section1 Other Container-Like Classes Qt includes other template classes that resemble containers in some respects. These classes don't provide iterators and cannot - be used with the \c foreach keyword. + be used with the \l foreach keyword. \list \li QCache<Key, T> provides a cache to store objects of a certain @@ -691,6 +502,29 @@ with the expected number of items before you insert the items. The next section discusses this topic in more depth. + \section1 Optimizations for Primitive and Relocatable Types + + Qt containers can use optimized code paths if the stored + elements are relocatable or even primitive. + However, whether types are primitive or relocatable + cannot be detected in all cases. + You can declare your types to be primitive or relocatable + by using the Q_DECLARE_TYPEINFO macro with the Q_PRIMITIVE_TYPE + flag or the Q_RELOCATABLE_TYPE flag. See the documentation + of Q_DECLARE_TYPEINFO for further details and usage examples. + + If you do not use Q_DECLARE_TYPEINFO, + Qt will use + \l {https://en.cppreference.com/w/cpp/types/is_trivial} {std::is_trivial_v<T>} + to identify primitive + types and it will require both + \l {https://en.cppreference.com/w/cpp/types/is_trivially_copyable} {std::is_trivially_copyable_v<T>} + and + \l {https://en.cppreference.com/w/cpp/types/is_destructible} {std::is_trivially_destructible_v<T>} + to identify relocatable types. + This is always a safe choice, albeit + of maybe suboptimal performance. + \section1 Growth Strategies QList<T>, QString, and QByteArray store their items @@ -707,39 +541,23 @@ We build the string \c out dynamically by appending one character to it at a time. Let's assume that we append 15000 characters to - the QString string. Then the following 18 reallocations (out of a - possible 15000) occur when QString runs out of space: 4, 8, 12, - 16, 20, 52, 116, 244, 500, 1012, 2036, 4084, 6132, 8180, 10228, - 12276, 14324, 16372. At the end, the QString has 16372 Unicode + the QString string. Then the following 11 reallocations (out of a + possible 15000) occur when QString runs out of space: 8, 24, 56, + 120, 248, 504, 1016, 2040, 4088, 8184, 16376. + At the end, the QString has 16376 Unicode characters allocated, 15000 of which are occupied. - The values above may seem a bit strange, but here are the guiding - principles: - \list - \li QString allocates 4 characters at a time until it reaches size 20. - \li From 20 to 4084, it advances by doubling the size each time. - More precisely, it advances to the next power of two, minus - 12. (Some memory allocators perform worst when requested exact - powers of two, because they use a few bytes per block for - book-keeping.) - \li From 4084 on, it advances by blocks of 2048 characters (4096 - bytes). This makes sense because modern operating systems - don't copy the entire data when reallocating a buffer; the - physical memory pages are simply reordered, and only the data - on the first and last pages actually needs to be copied. - \endlist + The values above may seem a bit strange, but there is a guiding + principle. It advances by doubling the size each time. + More precisely, it advances to the next power of two, minus + 16 bytes. 16 bytes corresponds to eight characters, as QString + uses UTF-16 internally. + + QByteArray uses the same algorithm as + QString, but 16 bytes correspond to 16 characters. - QByteArray uses more or less the same algorithm as - QString. - - QList<T> also uses that algorithm for data types that can be - moved around in memory using \c memcpy() (including the basic C++ - types, the pointer types, and Qt's \l{shared classes}) but uses a - different algorithm for data types that can only be moved by - calling the copy constructor and a destructor. Since the cost of - reallocating is higher in that case, QList<T> reduces the - number of reallocations by always doubling the memory when - running out of space. + QList<T> also uses that algorithm, but 16 bytes correspond to + 16/sizeof(T) elements. QHash<Key, T> is a totally different case. QHash's internal hash table grows by powers of two, and each time it grows, the items diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc index d881a32e62..7922fd9477 100644 --- a/src/corelib/doc/src/custom-types.qdoc +++ b/src/corelib/doc/src/custom-types.qdoc @@ -1,36 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page custom-types.html \title Creating Custom Qt Types \brief How to create and register new types with Qt. - \ingroup best-practices + \ingroup how-to \tableofcontents @@ -61,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. @@ -77,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}. @@ -101,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 @@ -131,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 @@ -155,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 303d374678..65b7eb5a20 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page datastreamformat.html @@ -31,7 +7,7 @@ \brief List of data types that can be serialized by QDataStream. The \l QDataStream class allows you to serialize the Qt data types - listed in this section as of \l{QDataStream::setVersion()}{version 18}. + listed in this section. It is always best to cast integers to a Qt integer type, such as \l{qint16} or \l{quint32}, when reading and writing. This ensures that @@ -55,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 @@ -63,33 +43,73 @@ \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} + \sa {JSON Support in Qt}, {CBOR Support in Qt} + */ diff --git a/src/corelib/doc/src/dontdocument.qdoc b/src/corelib/doc/src/dontdocument.qdoc index 9ed5345777..456e6dfab2 100644 --- a/src/corelib/doc/src/dontdocument.qdoc +++ b/src/corelib/doc/src/dontdocument.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \dontdocument (QMacAutoReleasePool QIncompatibleFlag QGenericAtomicOps QAtomicTraits diff --git a/src/corelib/doc/src/eventsandfilters.qdoc b/src/corelib/doc/src/eventsandfilters.qdoc index 947a24f4e5..38a4d2a39a 100644 --- a/src/corelib/doc/src/eventsandfilters.qdoc +++ b/src/corelib/doc/src/eventsandfilters.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group events diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc index f16a21d521..b787651aba 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -47,21 +23,151 @@ */ /*! - \externalpage http://www.ietf.org/rfc/rfc4648.txt - \title RFC 4648 -*/ - -/*! \externalpage http://www.iana.org/assignments/character-sets/character-sets.xml \title IANA character-sets encoding file */ /*! - \externalpage http://marcmutz.wordpress.com/effective-qt/containers/#containers-qlist + \externalpage https://marcmutz.wordpress.com/effective-qt/containers/#containers-qlist \title Pros and Cons of Using QList */ /*! - \externalpage http://marcmutz.wordpress.com/effective-qt/containers/ + \externalpage https://marcmutz.wordpress.com/effective-qt/containers/ \title Understand the Qt Containers */ + +/*! + \externalpage https://developer.android.com/training/articles/perf-jni#javavm-and-jnienv + \title JNI tips: JavaVM and JNIEnv +*/ + +/*! + \externalpage https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html + \title Java Native Interface Specification +*/ + +/*! + \externalpage https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html + \title Java: JNI Functions +*/ + +/*! + \externalpage https://docs.oracle.com/javase/8/docs/technotes/guides/jni/spec/design.html#global_and_local_references + \title JNI Design Overview: Global and Local References +*/ + +/*! + \externalpage https://developer.android.com/training/articles/perf-jni#local-and-global-references + \title JNI tips: Local and global references +*/ + +/*! + \externalpage https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#attach_current_thread + \title Java: AttachCurrentThread +*/ + +/*! + \externalpage https://docs.oracle.com/en/java/javase/13/docs/specs/jni/functions.html#interface-function-table + \title Java: Interface Function Table +*/ + +/*! + \externalpage https://doc.qt.io/qtcreator/creator-deploying-android.html#editing-manifest-files + \title Qt Creator: Editing Manifest Files +*/ + +/*! + \externalpage https://developer.android.com/training/articles/perf-anr + \title Android: Keeping your app responsive +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage/shared/documents-files + \title Android: Access documents and other files from shared storage +*/ + +/*! + \externalpage https://developer.android.com/reference/androidx/documentfile/provider/DocumentFile#getParentFile() + \title Android: DocumentFile.getParentFile() +*/ + +/*! + \externalpage https://developer.android.com/guide/topics/providers/content-provider-basics#ContentURIs + \title Android: Content URIs +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage#scoped-storage + \title Android: Scoped storage +*/ + +/*! + \externalpage https://developer.android.com/training/data-storage/use-cases + \title Android: storage best practices +*/ + +/*! + \externalpage https://developer.android.com/reference/android/provider/MediaStore + \title Android: MediaStore +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html + \title GNUInstallDirs +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html + \title CMAKE_INSTALL_PREFIX +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#command-line-cmake-tool + \title Command Line cmake invocation +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/envvar/DESTDIR.html + \title DESTDIR +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/install.html#targets + \title install(TARGETS) +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/install.html#script + \title install(SCRIPT) +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/command/add_subdirectory.html + \title add_subdirectory() +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/module/FetchContent.html#command:fetchcontent_makeavailable + \title FetchContent_MakeAvailable() +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/prop_gbl/USE_FOLDERS.html + \title USE_FOLDERS +*/ + +/*! + \externalpage https://cmake.org/cmake/help/latest/prop_tgt/FOLDER.html + \title FOLDER +*/ + +/*! + \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/filestorage.qdoc b/src/corelib/doc/src/filestorage.qdoc index e291ba1375..6c93955320 100644 --- a/src/corelib/doc/src/filestorage.qdoc +++ b/src/corelib/doc/src/filestorage.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page io-functions.html diff --git a/src/corelib/doc/src/foreach-keyword.qdoc b/src/corelib/doc/src/foreach-keyword.qdoc new file mode 100644 index 0000000000..b3a4482528 --- /dev/null +++ b/src/corelib/doc/src/foreach-keyword.qdoc @@ -0,0 +1,87 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page foreach-keyword.html + \title Qt's foreach Keyword + \ingroup groups + \ingroup qt-basic-concepts + + \brief Qt's foreach keyword. + + \tableofcontents + + \target foreach-keyword + \section1 The foreach Keyword + + \note The foreach keyword was introduced before the C++11 range-based loops + existed. New code should prefer C++11 range-based loops. + + The \c foreach keyword is a Qt-specific addition to the C++ language, + and is implemented using the preprocessor. + + Its syntax is: \c foreach (\e variable, \e container) \e + statement. For example, here's how to use \c foreach to iterate + over a QList<QString>: + + \snippet code/doc_src_containers.cpp 15 + + The \c foreach code is significantly shorter than the equivalent + code that uses iterators: + + \snippet code/doc_src_containers.cpp 16 + + 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: + + \snippet code/doc_src_containers.cpp 17 + + And like any other C++ loop construct, you can use braces around + the body of a \c foreach loop, and you can use \c break to leave + the loop: + + \snippet code/doc_src_containers.cpp 18 + + With QMap and QHash, \c foreach accesses the value component of + the (key, value) pairs automatically, so you should not call + values() on the container (it would generate an unnecessary copy, + see below). If you want to iterate over both the keys and the + values, you can use iterators (which are faster), or you can + obtain the keys, and use them to get the values too: + + \snippet code/doc_src_containers.cpp 19 + + For a multi-valued map: + + \snippet code/doc_src_containers.cpp 20 + + Qt automatically takes a copy of the container when it enters a + \c foreach loop. If you modify the container as you are + iterating, that won't affect the loop. (If you do not modify the + container, the copy still takes place, but thanks to \l{implicit + sharing} copying a container is very fast.) + + Since foreach creates a copy of the container, using a non-const + reference for the variable does not allow you to modify the original + container. It only affects the copy, which is probably not what you + want. + + An alternative to Qt's \c foreach loop is the range-based \c for that is + part of C++11 and newer. However, keep in mind that the range-based + \c for might force a Qt container to \l{Implicit Sharing}{detach}, whereas + \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 + + Defining this macro removes the availability of Qt's \c foreach + loop. +*/ diff --git a/src/corelib/doc/src/implicit-sharing.qdoc b/src/corelib/doc/src/implicit-sharing.qdoc index d789f8bf92..46daebe311 100644 --- a/src/corelib/doc/src/implicit-sharing.qdoc +++ b/src/corelib/doc/src/implicit-sharing.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /* TODO: Move some of the documentation from QSharedDataPointer into this document. */ diff --git a/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc new file mode 100644 index 0000000000..0521aff662 --- /dev/null +++ b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc @@ -0,0 +1,13 @@ +On Android, some limitations apply when dealing with +\l {Android: Content URIs}{content URIs}: +\list + \li Access permissions might be needed by prompting the user through the + \l QFileDialog which implements + \l {Android: Access documents and other files from shared storage}{Android's native file picker}. + \li Aim to follow the \l {Android: Scoped storage}{Scoped storage} guidelines, + such as using app specific directories instead of other public external directories. + For more information, also see + \l {Android: storage best practices}{storage best practices}. + \li Due to the design of Qt APIs (e.g. QFile), it's not possible to fully + integrate the latter APIs with Android's \l {Android: MediaStore}{MediaStore} APIs. +\endlist diff --git a/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc b/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc new file mode 100644 index 0000000000..47133f6d10 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc @@ -0,0 +1,8 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [warning] +\warning If your \e Android project is built using a CMake version lower than +3.19, make sure that you call \l{qt_finalize_project}{qt6_finalize_project()} at +the end of a top-level CMakeLists.txt. +//! [warning] diff --git a/src/corelib/doc/src/includes/cmake-android-supported-abis.qdocinc b/src/corelib/doc/src/includes/cmake-android-supported-abis.qdocinc new file mode 100644 index 0000000000..887866739c --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-android-supported-abis.qdocinc @@ -0,0 +1 @@ +The supported ABIs are \c{armeabi-v7a, arm64-v8a, x86, x86_64}. 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 new file mode 100644 index 0000000000..632ddf756f --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc @@ -0,0 +1,30 @@ +\badcode +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() + +qt_add_executable(MyApp main.cpp) + +set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") +file(GENERATE OUTPUT ${deploy_script} CONTENT " + +set(QT_DEPLOY_PLUGINS_DIR \"mypluginsdir\") +set(QT_DEPLOY_QML_DIR \"myqmldir\") +set(QT_DEPLOY_TRANSLATIONS_DIR \"i18n\") + +include(\"${QT_DEPLOY_SUPPORT}\") + +qt_deploy_runtime_dependencies( + EXECUTABLE \"\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>\" +)") + +install(SCRIPT ${deploy_script}) +\endcode 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-runtime-dependencies.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc new file mode 100644 index 0000000000..6d026d6301 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc @@ -0,0 +1,46 @@ +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +set_target_properties(MyApp PROPERTIES + WIN32_EXECUTABLE TRUE + MACOSX_BUNDLE TRUE +) + +# App bundles on macOS have an .app suffix +if(APPLE) + set(executable_path "$<TARGET_FILE_NAME:MyApp>.app") +else() + set(executable_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>") +endif() + +# Helper app, not necessarily built as part of this project. +qt_add_executable(HelperApp helper.cpp) +set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>") + +# 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}\" + ADDITIONAL_EXECUTABLES \"${helper_app_path}\" + GENERATE_QT_CONF + VERBOSE +)") + +# Omitting RUNTIME DESTINATION will install a non-bundle target to CMAKE_INSTALL_BINDIR, +# which coincides with the default value of QT_DEPLOY_BIN_DIR used above, './bin'. +# Installing macOS bundles always requires an explicit BUNDLE DESTINATION option. +install(TARGETS MyApp HelperApp # Install to CMAKE_INSTALL_PREFIX/bin/MyApp.exe + # and ./binHelperApp.exe + BUNDLE DESTINATION . # Install to CMAKE_INSTALL_PREFIX/MyApp.app/Contents/MacOS/MyApp +) +install(SCRIPT ${deploy_script}) # Add its runtime dependencies +\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 new file mode 100644 index 0000000000..27e04b5b08 --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc @@ -0,0 +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-find-package-core.qdocinc b/src/corelib/doc/src/includes/cmake-find-package-core.qdocinc new file mode 100644 index 0000000000..66649eec5a --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-find-package-core.qdocinc @@ -0,0 +1,6 @@ +The command is defined in the \c Core component of the \c Qt6 package, which +can be loaded like so: + +\badcode +find_package(Qt6 REQUIRED COMPONENTS Core) +\endcode 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/cmake-generate-deploy-app-script.qdocinc b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script.qdocinc new file mode 100644 index 0000000000..d5c1d2cf4a --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script.qdocinc @@ -0,0 +1,21 @@ +\badcode +cmake_minimum_required(VERSION 3.16...3.22) +project(MyThings) + +find_package(Qt6 REQUIRED COMPONENTS Core) +qt_standard_project_setup() + +qt_add_executable(MyApp main.cpp) + +install(TARGETS MyApp + BUNDLE DESTINATION . + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} +) + +qt_generate_deploy_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + NO_UNSUPPORTED_PLATFORM_ERROR +) +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/permissions.qdocinc b/src/corelib/doc/src/includes/permissions.qdocinc new file mode 100644 index 0000000000..00bf848d37 --- /dev/null +++ b/src/corelib/doc/src/includes/permissions.qdocinc @@ -0,0 +1,51 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [requestPermission-functor] + When the request is ready, \a functor will be called as + \c {functor(const QPermission &permission)}, with + \c permission describing the result of the request. +//! [requestPermission-functor] + +//! [requestPermission-postamble] + If the user explicitly grants the application the requested \a permission, + or the \a permission is known to not require user authorization on the given + platform, the status will be Qt::PermissionStatus::Granted. + + If the user explicitly denies the application the requested \a permission, + or the \a permission is known to not be accessible or applicable to applications + on the given platform, the status will be Qt::PermissionStatus::Denied. + + The result of a request will never be Qt::PermissionStatus::Undetermined. + + \note Permissions can only be requested from the main thread. +//! [requestPermission-postamble] + +//! [permission-metadata] + \inmodule QtCore + \inheaderfile QPermissions + \ingroup permissions + \since 6.5 + \sa QPermission, + QCoreApplication::requestPermission(), + QCoreApplication::checkPermission(), + {Application Permissions} +//! [permission-metadata] + +//! [begin-usage-declarations] + To request this permission at runtime, the following platform + specific usage declarations have to be made at build time: + + \table + \header + \li Platform + \li Type + \li +//! [begin-usage-declarations] + +//! [end-usage-declarations] + \endtable + + Please see the individual usage declaration types for how + to add them to your project. +//! [end-usage-declarations] diff --git a/src/corelib/doc/src/includes/qfile-copy.qdocinc b/src/corelib/doc/src/includes/qfile-copy.qdocinc new file mode 100644 index 0000000000..5ff68eac81 --- /dev/null +++ b/src/corelib/doc/src/includes/qfile-copy.qdocinc @@ -0,0 +1,11 @@ +This file is closed before it is copied. + +If the copied file is a symbolic link (symlink), the +file it refers to is copied, not the link itself. With the +exception of permissions, which are copied, no other file metadata +is copied. + +Returns \c true if successful; otherwise returns \c false. + +Note that if a file with the name \a newName already exists, +copy() returns \c false. This means QFile will not overwrite it. diff --git a/src/corelib/doc/src/includes/qobject.qdocinc b/src/corelib/doc/src/includes/qobject.qdocinc new file mode 100644 index 0000000000..65630c82ee --- /dev/null +++ b/src/corelib/doc/src/includes/qobject.qdocinc @@ -0,0 +1,10 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [disconnect-all] +\note Disconnecting all signal-slot connections will also disconnect the +\l QObject::destroyed() signal if it is connected. Doing so can adversely +affect classes that rely on this signal for cleaning up resources. It is +recommended to disconnect only the specific signals that were connected by +application code. +//! [disconnect-all] diff --git a/src/corelib/doc/src/includes/qstring.qdocinc b/src/corelib/doc/src/includes/qstring.qdocinc new file mode 100644 index 0000000000..66ed12dff3 --- /dev/null +++ b/src/corelib/doc/src/includes/qstring.qdocinc @@ -0,0 +1,36 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +// \1 is either "search" or "comparison" +//! [search-comparison-case-sensitivity] +If \a cs is Qt::CaseSensitive (the default), the \1 is case-sensitive; +otherwise the \1 is case-insensitive. +//! [search-comparison-case-sensitivity] + +//! [negative-index-start-search-from-end] +If \a from is -1, the search starts at the last character; if it is +-2, at the next to last character and so on. +//! [negative-index-start-search-from-end] + +//! [qstring-first-index-of] +Returns the index position of the first occurrence of the \1 \a \2 +in this string, searching forward from index position \a from. +Returns -1 if \a \2 is not found. +//! [qstring-first-index-of] + +//! [qstring-last-index-of] +Returns the index position of the last occurrence of the \1 \a \2 +in this string, searching backward from index position \a from. +//! [qstring-last-index-of] + +//! [qstring-local-8-bit-equivalent] +On Unix systems this is equivalent to \1(). +Note that on Apple systems this function does not take +\l{https://developer.apple.com/documentation/foundation/nsstring/1410091-defaultcstringencoding?language=objc} +{NSString.defaultCStringEncoding} or +\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. +On Windows the system's current code page is used. +//! [qstring-local-8-bit-equivalent] diff --git a/src/corelib/doc/src/includes/qt_add_big_resources.qdocinc b/src/corelib/doc/src/includes/qt_add_big_resources.qdocinc deleted file mode 100644 index 0a76bdd844..0000000000 --- a/src/corelib/doc/src/includes/qt_add_big_resources.qdocinc +++ /dev/null @@ -1,44 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [description] -Creates compiled object files from Qt resource files using the -\l{Resource Compiler (rcc)}. Paths to the generated files are added to -\c{<VAR>}. - -This is similar to \l qt5_add_resources / \l qt_add_resources, but directly -generates object files (\c .o, \c .obj) files instead of C++ source code. -This allows to embed bigger resources, where compiling to C++ sources and then -to binaries would be too time consuming or memory intensive. - -\note This macro is only available if using \c{CMake} 3.9 or later. -//! [description] - -//! [arguments] -You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. -You can find possible options in the \l{rcc}{rcc documentation}. -//! [arguments] diff --git a/src/corelib/doc/src/includes/qt_add_binary_resources.qdocinc b/src/corelib/doc/src/includes/qt_add_binary_resources.qdocinc deleted file mode 100644 index 21d3ca5990..0000000000 --- a/src/corelib/doc/src/includes/qt_add_binary_resources.qdocinc +++ /dev/null @@ -1,39 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [description] -Adds a custom \c target that compiles Qt resource files into a binary \c{.rcc} -file. -//! [description] - -//! [arguments] -\c{DESTINATION} sets the path of the generated \c{.rcc} file. The default is -\c{${CMAKE_CURRENT_BINARY_DIR}/${target}.rcc}. - -You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. -You can find possible options in the \l{rcc}{rcc documentation}. -//! [arguments] diff --git a/src/corelib/doc/src/includes/qt_add_resources.qdocinc b/src/corelib/doc/src/includes/qt_add_resources.qdocinc deleted file mode 100644 index b3c032a04b..0000000000 --- a/src/corelib/doc/src/includes/qt_add_resources.qdocinc +++ /dev/null @@ -1,40 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [description] -Creates source code from Qt resource files using the -\l{Resource Compiler (rcc)}. Paths to the generated source files are added to -\c{<VAR>}. - -\note This is a low-level macro. See the \l{CMake AUTORCC Documentation} for a -more convenient way to let Qt resource files be processed with \c{rcc}. -//! [description] - -//! [arguments] -You can set additional \c{OPTIONS} that should be added to the \c{rcc} calls. -You can find possible options in the \l{rcc}{rcc documentation}. -//! [arguments] diff --git a/src/corelib/doc/src/includes/qt_generate_moc.qdocinc b/src/corelib/doc/src/includes/qt_generate_moc.qdocinc deleted file mode 100644 index c1c0ada978..0000000000 --- a/src/corelib/doc/src/includes/qt_generate_moc.qdocinc +++ /dev/null @@ -1,42 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [description] -Creates a rule to call the \l{moc}{Meta-Object Compiler (moc)} on \c src_file -and store the output in \c dest_file. - -\note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a -more convenient way to let source files be processed with \c{moc}. -\l qt5_wrap_cpp is also similar, but automatically generates a temporary file -path for you. -//! [description] - -//! [arguments] -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}. -//! [arguments] diff --git a/src/corelib/doc/src/includes/qt_import_plugins.qdocinc b/src/corelib/doc/src/includes/qt_import_plugins.qdocinc deleted file mode 100644 index 005a73d1d7..0000000000 --- a/src/corelib/doc/src/includes/qt_import_plugins.qdocinc +++ /dev/null @@ -1,58 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [description] -Specifies a custom set of plugins to import. The optional arguments: -\c INCLUDE, \c EXCLUDE, \c INCLUDE_BY_TYPE, and \c EXCLUDE_BY_TYPE, -can be used more than once. - -This CMake command was introduced in Qt 5.14. - -\list -\li \c INCLUDE -- can be used to specify a list of plugins to import. -\li \c EXCLUDE -- can be used to specify a list of plugins to exclude. -\li \c INCLUDE_BY_TYPE -- can be used to override the list of plugins to - import for a certain plugin type. -\li \c EXCLUDE_BY_TYPE -- can be used to specify a plugin type to exclude; - then no plugins of that type are imported. -\endlist - -Qt provides plugin types such as \c imageformats, \c platforms, -and \c sqldrivers. - -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 -\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. -//! [description] diff --git a/src/corelib/doc/src/includes/qt_wrap_cpp.qdocinc b/src/corelib/doc/src/includes/qt_wrap_cpp.qdocinc deleted file mode 100644 index 3f6b278557..0000000000 --- a/src/corelib/doc/src/includes/qt_wrap_cpp.qdocinc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [description] -Creates rules for calling the \l{moc}{Meta-Object Compiler (moc)} on the given -source files. For each input file, an output file is generated in the build -directory. The paths of the generated files are added to \c{<VAR>}. - -\note This is a low-level macro. See the \l{CMake AUTOMOC Documentation} for a -more convenient way to let source files be processed with \c{moc}. -//! [description] - -//! [arguments] -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}. - -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}. - -\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 -Q_PLUGIN_METADATA() macro. -//! [arguments] diff --git a/src/corelib/doc/src/io.qdoc b/src/corelib/doc/src/io.qdoc index a1bbc623a1..443d324f75 100644 --- a/src/corelib/doc/src/io.qdoc +++ b/src/corelib/doc/src/io.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group io @@ -34,7 +10,7 @@ network handling. These \l{Qt Core} classes are used to handle input and output to and from - external devices, processes, files etc. as well as manipulating files and + external devices, processes, files etc., as well as manipulating files and directories. */ diff --git a/src/corelib/doc/src/ipc.qdoc b/src/corelib/doc/src/ipc.qdoc new file mode 100644 index 0000000000..7ec6f5fa3b --- /dev/null +++ b/src/corelib/doc/src/ipc.qdoc @@ -0,0 +1,492 @@ +// Copyright (C) 2022 Intel Corporation. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page ipc.html + \title Inter-Process Communication + \ingroup groups + \ingroup frameworks-technologies + \keyword ipc + \ingroup explanations-networkingandconnectivity + + \brief An overview of Qt's inter-process communication functionality + + Qt supports many ways of communicating with other processes running in the + same system or in different systems. There are basically three types of + inter-process communication mechanisms: + + \list 1 + \li Synchronization primitives + \li Exchanging of arbitrary byte-level data + \li Passing structured messages + \endlist + + \section1 Synchronization primitives + + Qt only provides one class for explicit inter-process synchronization: + \l{QSystemSemaphore}. A QSystemSemaphore is like a \l{QSemaphore} that is + accessible by multiple processes in the same system. It is globally + identified by a "key", which in Qt is represented by the \l{QNativeIpcKey} + class. Additionally, depending on the OS, Qt may support multiple different + backends for sharing memory; see the \l{Native IPC Keys} documentation for + more information and limitations. + + It is possible to use regular thread-synchronization primitives such as + mutexes, wait conditions, and read-write locks, located in memory that is + shared between processes. Qt does not provide any class to support this, + but applications can use low-level operations on certain operating systems. + + Other Qt classes may be used to provide higher-level locking, like + \l{QLockFile}, or by acquiring a unique, system-wide resource. Such + techniques include \l{QTcpServer}{TCP} or \l{QUdpSocket}{UDP} ports or + well-known names in \l{QDBusConnection::registerService}{D-Bus}. + + \section1 Byte-level data sharing + + Using byte-level data, applications can implement any communication + protocol they may choose. Sharing of byte data can be stream-oriented + (serialized) or can allow random access (a similar condition to + QFileDevice::isSequential()). + + For serial communication, Qt provides a number of different classes and + even full modules: + \list + \li Pipes and FIFOs: \l QFile + \li Child processes: \l QProcess + \li Sockets: \l QTcpSocket, \l QUdpSocket (in \l{Qt Network}) + \li HTTP(S): \l QNetworkAccessManager (in \l{Qt Network}) and + \l QHttpServer (in \l{Qt HTTP Server}) + \li CoAP(S): \l QCoapClient (in \l{Qt CoAP}) + \endlist + + For random-access data sharing within the same system, Qt provides + \l{QSharedMemory}. See the \l{Shared Memory} documentation for detailed + information. + + \section1 Structured message passing + + Qt also provides a number of techniques to exchange structured messages + with other processes. Applications can build on top of the byte-level + solutions above, such as by using \l QJsonDocument or \l QXmlStreamReader / + \l QXmlStreamWriter over HTTP to perform JSONRPC or XMLRPC, respectively, + or \l QCborValue with QtCoAP. + + Dedicated Qt modules for structured messages and remote procedure-calling + include: + \list + \li \l{Qt D-Bus} + \li \l{Qt Remote Objects} + \li \l{Qt WebSockets} + \endlist +*/ + +/*! + \page shared-memory.html + \title Shared Memory + \keyword ipc + \keyword shared memory + + \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 + that is shared with other processes is often referred to as a "segment", + and although it may have been implemented as specific segments on + processors with segmented memory models in the past, this is not the case + in any modern operating system. Shared memory segments are simply regions + of memory that the operating system will ensure are available to all + processes participating. + + \note The address at which the segment is located in memory will almost + always be different for each process that is participating in the sharing. + Therefore, applications must take care to share only position-independent + data, such as primitive C++ types or arrays of such types. + + \section1 Sharing memory using QSharedMemory + + QSharedMemory provides a simple API to create a shared memory segment of a + given size or attach to one that was created by another process. + Additionally, it provides a pair of methods to \l{QSharedMemory::}{lock} + and \l{QSharedMemory::}{unlock} the whole segment, using an internal + \l{QSystemSemaphore}. + + Shared memory segments and system semaphores are globally identified in the + system through a "key", which in Qt is represented by the \l{QNativeIpcKey} + class. Additionally, depending on the OS, Qt may support multiple different + backends for sharing memory; see the \l{Native IPC Keys} documentation for + more information and limitations. + + QSharedMemory is designed to share memory only within the same privilege + level (that is, not with untrusted other processes, such as those started + by other users). For backends that support it, QSharedMemory will create + segments such that only processes with the same privilege level can attach. + + \section1 Sharing memory via memory-mapped files + + Most files can be mapped to memory using QFile::map() and, if the + \l{QFileDevice::MapPrivateOption}{MapPrivateOption} option is not specified, + any writes to the mapped segment will be observed by all other processes + that have mapped the same file. Exceptions to files that can be mapped to + memory include remote files found in network shares or those located in + certain filesystems. Even if the operating system does allow mapping remote + files to memory, I/O operations on the file will likely be cached and + delayed, thus making true memory sharing impossible. + + This solution has the major advantages of being independent of any backend + API and of being simpler to interoperate with from non-Qt applications. + Since \l{QTemporaryFile} is a \l{QFile}, applications can use that class to + achieve clean-up semantics and to create unique shared memory segments too. + + To achieve locking of the shared memory segment, applications will need to + deploy their own mechanisms. One way may be to use \l QLockFile. Another + and less costly solution is to use QBasicAtomicInteger or \c{std::atomic} in + a pre-determined offset in the segment itself. Higher-level locking + primitives may be available on some operating systems; for example, on + Linux, applications can set the "pshared" flag in the mutex attribute + passed to \c{pthread_mutex_create()} to indicate that the mutex resides in + a shared memory segment. + + Be aware that the operating system will likely attempt to commit to + permanent storage any writes made to the shared memory. This may be desired + or it may be a performance penalty if the file itself was meant to be + temporary. In that case, applications should locate a RAM-backed + filesystem, such as \c{tmpfs} on Linux (see + QStorageInfo::fileSystemType()), or pass a flag to the native file-opening + function to inform the OS to avoid committing the contents to storage. + + It is possible to use file-backed shared memory to communicate with + untrusted processes, in which case the application should exercise great + care. The files may be truncated/shrunk and cause applications accessing + memory beyond the file's size to crash. + + \section2 Linux hints on memory-mapped files + + On modern Linux systems, while the \c{/tmp} directory is often a \c{tmpfs} + mount point, that is not a requirement. However, the \c{/dev/shm} directory + is required to be a \c{tmpfs} and exists for the very purpose of sharing + memory. Do note that it is world-readable and writable (like \c{/tmp} and + \c{/var/tmp}), so applications must be careful of the contents revealed + there. Another alternative is to use the XDG Runtime Directory (see + QStandardPaths::writableLocation() and \l{QStandardPaths::RuntimeLocation}), + which on Linux systems using systemd is a user-specific \c{tmpfs}. + + An even more secure solution is to create a "memfd" using \c{memfd_create(2)} + and use interprocess communication to pass the file descriptor, like + \l{QDBusUnixFileDescriptor} or by letting the child process of a \l{QProcess} + inherit it. "memfds" can also be sealed against being shrunk, so they are + safe to be used when communicating with processes with a different privilege + level. + + \section2 FreeBSD hints on memory-mapped files + + FreeBSD also has \c{memfd_create(2)} and can pass file descriptors to other + processes using the same techniques as Linux. It does not have temporary + filesystems mounted by default. + + \section2 Windows hints on memory-mapped files + + On Windows, the application can request the operating system avoid saving + the file's contents on permanent storage. This request is performed by + passing the \c{FILE_ATTRIBUTE_TEMPORARY} flag in the + \c{dwFlagsAndAttributes} parameter to the \c{CreateFile} Win32 function, + the \c{_O_SHORT_LIVED} flag to \c{_open()} low-level function, or by + including the modifier "T" to the + \c{fopen()} C runtime function. + + There's also a flag to inform the operating system to delete the file when + the last handle to it is closed (\c{FILE_FLAG_DELETE_ON_CLOSE}, + \c{_O_TEMPORARY}, and the "D" modifier), but do note that all processes + attempting to open the file must agree on using this flag or not using it. A + mismatch will likely cause a sharing violation and failure to open the file. +*/ + +/*! + \page native-ipc-keys.html + \title Native IPC Keys + \keyword ipc + \keyword shared memory + \keyword system semaphore + + \brief An overview of keys for QSharedMemory and QSystemSemaphore + + The \l QSharedMemory and \l QSystemSemaphore classes identify their + resource using a system-wide identifier known as a "key". The low-level key + value as well as the key type are encapsulated in Qt using the \l + QNativeIpcKey class. That class also provides the proper means of + exchanging the key with other processes, by way of + QNativeIpcKey::toString() and QNativeIpcKey::fromString(). + + Qt currently supports three distinct backends for those two classes, which + match the values available in the \l{QNativeIpcKey::Type} enumeration. + \list + \li POSIX Realtime extensions (IEEE 1003.1b, POSIX.1b) + \li X/Open System Interfaces (XSI) or System V (SVr4), though also now part of POSIX + \li Windows primitives + \endlist + + As the name indicates, the Windows primitives are only available on the + Windows operating system, where they are the default backend. The other two + are usually both available on Unix operating systems. The following table + provides an overview of typical availability since Qt 6.6: + + \table + \header \li Operating system \li POSIX \li System V \li Windows + \row \li Android \li \li \li + \row \li INTEGRITY \li \li \li + \row \li QNX \li Yes \li \li + \row \li \macos \li Yes \li Usually (1) \li + \row \li Other Apple OSes \li Yes \li \li + \row \li Other Unix systems \li Yes \li Yes \li + \row \li Windows \li Rarely (2) \li \li Yes + \endtable + + \note 1 Sandboxed \macos applications, which include all applications + distributed via the Apple App Store, may not use System V objects. + + \note 2 Some GCC-compatible C runtimes on Windows provide POSIX-compatible + shared memory support, but this is rare. It is always absent with the + Microsoft compiler. + + To determine whether a given key type is supported, applications should + call QSharedMemory::isKeyTypeSupported() and + QSystemSemaphore::isKeyTypeSupported(). + + QNativeIpcKey also provides support for compatibility with Qt applications + prior to its introduction. The following sections detail the limitations of + the backends, the contents of the string keys themselves, and + compatibility. + + \section1 Cross-platform safe key format + + QNativeIpcKey::setNativeKey() and QNativeIpcKey::nativeKey() handle the + low-level native key, which may be used with the native APIs and shared + with other, non-Qt processes (see below for the API). This format is not + usually cross-platform, so both QSharedMemory and QSystemSemaphore provide + a function to translate a cross-platform identifier string to the native + key: QSharedMemory::platformSafeKey() and + QSystemSemaphore::platformSafeKey(). + + The length of the cross-platform key on most platforms is the same as that + of a file name, but is severely limited on Apple platforms to only 30 + usable bytes (be mindful of UTF-8 encoding if using characters outside the + US-ASCII range). The format of the key is also similar to that of a file + path component, meaning it should not contain any characters not allowed in + 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". 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 + format: \c {<application group identifier>/<custom identifier>}. Sandboxing + is implied for all applications distributed through the Apple App Store. + See Apple's documentation + \l{https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW24} + {here} and \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_application-groups} + {here} for more information, including how to obtain the application's group identifier. + + \section1 Native key format + + This section details the format of the native keys of the supported + backends. + + \section3 POSIX Realtime + Native keys resemble file names and may contain any character that file + names do, except for a slash. POSIX requires the first character in the key + name to be a slash and leaves undetermined whether any additional slashes + are permitted. On most operating systems, the key length is the same as a + file name, but it is limited to 32 characters on Apple operating systems + (this includes the first slash and the terminating null, so only 30 usable + characters are possible). + + The following are good examples of native POSIX keys: "/myapp", + "/org.example.myapp", "/org.example.myapp-12345". + + QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey() + simply prepend the slash. On Apple operating systems, they also truncate + the result to the available size. + + \section3 Windows + Windows key types are NT + \l{https://learn.microsoft.com/en-us/windows/win32/sync/object-namespaces}{kernel + object names} and may be up to \c{MAX_PATH} (260) characters in length. + They look like relative paths (that is, they don't start with a backslash + or a drive letter), but unlike file names on Windows, they are + case-sensitive. + + The following are good examples of native Windows keys: "myapp", + "org.example.myapp", "org.example.myapp-12345". + + QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey() + insert a prefix to disambiguate shared memory and system semaphores, + respectively. + + \section3 X/Open System Interfaces (XSI) / System V + System V keys take the form of the name of a file in the system, and thus + have the exact same limitations as file paths do. Both QSharedMemory and + QSystemSemaphore will create this file if it does not exist when creating + the object. If auto-removal is disabled, it may also be shared between + QSharedMemory and QSystemSemaphore without conflict and can be any extant + file (for example, it can be the process executable itself, see + QCoreApplication::applicationFilePath()). The path should be an absolute + one to avoid mistakes due to different current directories. + + QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey() + always return an absolute path. If the input was already absolute, they + will return their input unchanged. Otherwise, they will prepend a suitable + path where the application usually has permission to create files in. + + \section1 Ownership + + Shared memory and system semaphore objects need to be created before use, + which is accomplished with QSharedMemory::create() or by passing + QSystemSemaphore::Create to the constructor, respectively. + + On Unix systems, the Qt classes that created the object will be responsible + for cleaning up the object in question. Therefore, if the application with + that C++ object exits uncleanly (a crash, qFatal(), etc.), the object may + be left behind. If that happens, applications may fail to create the + object again and should instead attach to an existing one. For example, for + QSharedMemory: + + \code + if (!shm.create(4096) && shm.error() == QSharedMemory::AlreadyExists) + shm.attach(); + \endcode + + Re-attaching to a QSystemSemaphore is probably unwise, as the token counter + in it is probably in an unknown state and therefore may lead to deadlocks. + + \section3 POSIX Realtime + POSIX Realtime object ownership is patterned after files, in the sense that + they exist independent of any process using them or not. Qt is unable to + determine if the object is still in use, so auto-removal will remove it + even then, which will make attaching to the same object impossible but + otherwise not affecting existing attachments. + + Prior to Qt 6.6, Qt never cleaned up POSIX Realtime objects, except on QNX. + + \section3 X/Open System Interfaces (XSI) / System V + There are two resources managed by the Qt classes: the file the key refers + to and the object itself. QSharedMemory manages the object cooperatively: + the last attachment is responsible for removing the object itself and then + removing the key file. QSystemSemaphore will remove the object if and only + if it was passed QSystemSemaphore::Create; additionally, if it created the + key file, it will remove that too. + + Since Qt 6.6, it is possible to ask either class not to clean up. + + \section3 Windows + The operating system owns the object and will clean up after the last + handle to the object is closed. + + \section1 Interoperability with old Qt applications + + The QNativeIpcKey class was introduced in Qt 6.6. Prior to this version, + QSharedMemory and QSystemSemaphore backends were determined at the time of + 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. 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. + + Qt 6.6 retains the configure script option but it no longer controls the + availability of the backends. Instead, it changes what + QNativeIpcKey::legacyDefaultTypeForOs() will return. Applications that need + to retain compatibility must use this key type exclusively to guarantee + interoperability. + + The API in both QSharedMemory and QSystemSemaphore had the concept of a + cross-platform key, which is now deprecated in favor of using + QSharedMemory::legacyNativeKey() and QSystemSemaphore::legacyNativeKey(). + Those two functions produce the same native key as the deprecated functions + did in prior versions. If the old code was for example: + + \code + QSharedMemory shm("org.example.myapplication"); + QSystemSemaphore sem("org.example.myapplication"); + \endcode + + It can be updated to be: + \code + QSharedMemory shm(QSharedMemory::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 + code such as: + + \code + QSharedMemory shm; + shm.setNativeKey(key); + \endcode + + Though if the older application did accept a native key, the new one may + opt to use \c{platformSafeKey()} with a second argument of + QNativeIpcKey::legacyDefaultTypeForOs(). + + \section3 X/Open System Interfaces (XSI) / System V + Never use existing files for QSharedMemory keys, as the old Qt application + may attempt to remove it. Instead, let QSharedMemory create it. + + \section1 Interoperability with non-Qt applications + + Interoperability with non-Qt applications is possible, with some limitations: + \list + \li Creation of shared memory segments must not race + \li QSharedMemory support for locking the segment is unavailable + \endlist + + Communication with non-Qt applications must always be through the native + key. + + QSharedMemory always maps the entire segment to memory. The non-Qt + application may choose to only map a subset of it to memory, with no ill + effects. + + \section3 POSIX Realtime + POSIX shared memory can be opened using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/shm_open.html}{shm_open()} + and POSIX system semaphores can be opened using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/sem_open.html}{sem_open()}. + + Both of those functions take a \c name parameter that is the result of + QNativeIpcKey::nativeKey(), encoded for file names using + QFile::encodeName() / QFile::decodeName(). + + \section3 Windows + Windows shared memory objects can be opened using + \l{https://learn.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-createfilemappingw}{CreateFileMappingW} + and Windows system semaphore objects can be opened using + \l{https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-createsemaphorew}{CreateSemaphoreW}. + Despite the name of both functions starting with "Create", they are able + to attach to existing objects. + + The \c lpName parameter to those functions is the result of + QNativeIpcKey::nativeKey(), without transformation. + + If the foreign application uses the non-Unicode version of those functions + (ending in "A"), the name can be converted to and from 8-bit using QString. + + \section3 X/Open System Interfaces (XSI) / System V + System V shared memory can be obtained using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/shmget.html}{shmget()} + and System V system semaphores can be obtained using + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/semget.html}{semget()}. + + The \c{key} parameter to either of those functions is the result of the + \l{https://pubs.opengroup.org/onlinepubs/9699919799/functions/ftok.html}{ftok()} + function when passed the file name obtained from QNativeIpcKey::nativeKey() + with an \c id of 81 or 0x51 (the ASCII capital letter 'Q'). + + System V semaphore objects may contain multiple semaphores, but + QSystemSemaphore only uses the first one (number 0 for \c{sem_num}). + + Both QSharedMemory and QSystemSemaphore default to removing the object + using the \c{IPC_RMID} operation to \c{shmctl()} and \c{semctl()} + respectively if they are the last attachment. +*/ diff --git a/src/corelib/doc/src/java-style-iterators.qdoc b/src/corelib/doc/src/java-style-iterators.qdoc new file mode 100644 index 0000000000..d486b73488 --- /dev/null +++ b/src/corelib/doc/src/java-style-iterators.qdoc @@ -0,0 +1,174 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page java-style-iterators.html + \title Java-style Iterators in Qt + \ingroup groups + \ingroup qt-basic-concepts + \brief Java style iterators for Qt's containers. + + \tableofcontents + + \section1 Java-Style Iterators + + For each container class, there are two Java-style iterator data + types: one that provides read-only access and one that provides + read-write access. + + \note New code should use \l{STL-Style iterators} since these are more efficient + and can be used together with Qt's and STL's \l{generic algorithms}. + + \table + \header \li Containers \li Read-only iterator + \li Read-write iterator + \row \li QList<T>, QQueue<T>, QStack<T>, \li QListIterator<T> + \li QMutableListIterator<T> + \row \li QSet<T> \li QSetIterator<T> + \li QMutableSetIterator<T> + \row \li QMap<Key, T>, QMultiMap<Key, T> \li QMapIterator<Key, T> + \li QMutableMapIterator<Key, T> + \row \li QHash<Key, T>, QMultiHash<Key, T> \li QHashIterator<Key, T> + \li QMutableHashIterator<Key, T> + \endtable + + In this discussion, we will concentrate on QList and QMap. The + iterator types for QSet have exactly + the same interface as QList's iterators; similarly, the iterator + types for QHash have the same interface as QMap's iterators. + + Unlike \l{STL-Style iterators}, Java-style iterators point \e between items + rather than directly \e at items. For this reason, they are either pointing + to the very beginning of the container (before the first item), at the very + end of the container (after the last item), or between two items. The + diagram below shows the valid iterator positions as red arrows for a list + containing four items: + + \image javaiterators1.png + + Here's a typical loop for iterating through all the elements of a + QList<QString> in order: + + \snippet code/doc_src_containers.cpp 1 + + It works as follows: The QList to iterate over is passed to the + QListIterator constructor. At that point, the iterator is located + just in front of the first item in the list (before item "A"). + Then we call \l{QListIterator::hasNext()}{hasNext()} to + check whether there is an item after the iterator. If there is, we + call \l{QListIterator::next()}{next()} to jump over that + item. The next() function returns the item that it jumps over. For + a QList<QString>, that item is of type QString. + + Here's how to iterate backward in a QList: + + \snippet code/doc_src_containers.cpp 2 + + The code is symmetric with iterating forward, except that we + start by calling \l{QListIterator::toBack()}{toBack()} + to move the iterator after the last item in the list. + + The diagram below illustrates the effect of calling + \l{QListIterator::next()}{next()} and + \l{QListIterator::previous()}{previous()} on an iterator: + + \image javaiterators2.png + + The following table summarizes the QListIterator API: + + \table + \header \li Function \li Behavior + \row \li \l{QListIterator::toFront()}{toFront()} + \li Moves the iterator to the front of the list (before the first item) + \row \li \l{QListIterator::toBack()}{toBack()} + \li Moves the iterator to the back of the list (after the last item) + \row \li \l{QListIterator::hasNext()}{hasNext()} + \li Returns \c true if the iterator isn't at the back of the list + \row \li \l{QListIterator::next()}{next()} + \li Returns the next item and advances the iterator by one position + \row \li \l{QListIterator::peekNext()}{peekNext()} + \li Returns the next item without moving the iterator + \row \li \l{QListIterator::hasPrevious()}{hasPrevious()} + \li Returns \c true if the iterator isn't at the front of the list + \row \li \l{QListIterator::previous()}{previous()} + \li Returns the previous item and moves the iterator back by one position + \row \li \l{QListIterator::peekPrevious()}{peekPrevious()} + \li Returns the previous item without moving the iterator + \endtable + + QListIterator provides no functions to insert or remove items + from the list as we iterate. To accomplish this, you must use + QMutableListIterator. Here's an example where we remove all + odd numbers from a QList<int> using QMutableListIterator: + + \snippet code/doc_src_containers.cpp 3 + + The next() call in the loop is made every time. It jumps over the + next item in the list. The + \l{QMutableListIterator::remove()}{remove()} function removes the + last item that we jumped over from the list. The call to + \l{QMutableListIterator::remove()}{remove()} does not invalidate + the iterator, so it is safe to continue using it. This works just + as well when iterating backward: + + \snippet code/doc_src_containers.cpp 4 + + If we just want to modify the value of an existing item, we can + use \l{QMutableListIterator::setValue()}{setValue()}. In the code + below, we replace any value larger than 128 with 128: + + \snippet code/doc_src_containers.cpp 5 + + Just like \l{QMutableListIterator::remove()}{remove()}, + \l{QMutableListIterator::setValue()}{setValue()} operates on the + last item that we jumped over. If we iterate forward, this is the + item just before the iterator; if we iterate backward, this is + the item just after the iterator. + + The \l{QMutableListIterator::next()}{next()} function returns a + non-const reference to the item in the list. For simple + operations, we don't even need + \l{QMutableListIterator::setValue()}{setValue()}: + + \snippet code/doc_src_containers.cpp 6 + + As mentioned above QSet's iterator + classes have exactly the same API as QList's. We will now turn to + QMapIterator, which is somewhat different because it iterates on + (key, value) pairs. + + Like QListIterator, QMapIterator provides + \l{QMapIterator::toFront()}{toFront()}, + \l{QMapIterator::toBack()}{toBack()}, + \l{QMapIterator::hasNext()}{hasNext()}, + \l{QMapIterator::next()}{next()}, + \l{QMapIterator::peekNext()}{peekNext()}, + \l{QMapIterator::hasPrevious()}{hasPrevious()}, + \l{QMapIterator::previous()}{previous()}, and + \l{QMapIterator::peekPrevious()}{peekPrevious()}. The key and + value components are extracted by calling \l{QMapIterator::key()}{key()} and \l{QMapIterator::value()}{value()} on + the object returned by next(), peekNext(), previous(), or + peekPrevious(). + + The following example removes all (capital, country) pairs where + the capital's name ends with "City": + + \snippet code/doc_src_containers.cpp 7 + + QMapIterator also provides a \l{QMapIterator::key()}{key()} and a \l{QMapIterator::value()}{value()} function that + operate directly on the iterator and that return the key and + value of the last item that the iterator jumped above. For + example, the following code copies the contents of a QMap into a + QHash: + + \snippet code/doc_src_containers.cpp 8 + + If we want to iterate through all the items with the same + value, we can use \l{QMapIterator::findNext()}{findNext()} + or \l{QMapIterator::findPrevious()}{findPrevious()}. + Here's an example where we remove all the items with a particular + value: + + \snippet code/doc_src_containers.cpp 9 + +*/ diff --git a/src/corelib/doc/src/json.qdoc b/src/corelib/doc/src/json.qdoc index a32772f910..98ae202cfa 100644 --- a/src/corelib/doc/src/json.qdoc +++ b/src/corelib/doc/src/json.qdoc @@ -1,36 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group json \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 @@ -40,12 +16,10 @@ now widely used as a data exchange format on the internet. The JSON support in Qt provides an easy to use C++ API to parse, - modify and save JSON data. It also contains support for saving this - data in a binary format that is directly "mmap"-able and very fast to - access. + modify and save JSON data. More details about the JSON data format can be found at \l{http://json.org}{json.org} - and in \l{http://tools.ietf.org/html/rfc4627}{RFC-4627}. + and in \l {RFC 4627}. \tableofcontents @@ -99,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 @@ -108,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 new file mode 100644 index 0000000000..9b3ea6ae66 --- /dev/null +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -0,0 +1,264 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page bindableproperties.html + \title Qt Bindable Properties + \brief Qt's bindable properties. + + \ingroup qt-basic-concepts + \keyword Qt's Bindable Properties + + Qt provides bindable properties. Bindable properties are properties + which either have a value or are specified using any C++ function, + typically a C++ lambda expression. + In case they are specified using a C++ function, they are + updated automatically whenever their dependencies change. + + Bindable properties are implemented in the class QProperty, which + consists of the data object and a pointer to a management data structure, and + in class QObjectBindableProperty, which consists only of the data object and + uses the encapsulating QObject to store the pointer to the + management data structure. + + \section1 Why Use Bindable Properties? + + Property bindings are one of the core features of QML. They allow to specify + relationships between different object properties and automatically update + properties' values whenever their dependencies change. Bindable properties + allow to achieve the same not only in QML code, but also in C++. Using + bindable properties can help to simplify your program, by eliminating a lot + of boilerplate code for tracking and reacting to dependency updates of + different objects. + + The \l {Introductory Example} below demonstrates the usage of bindable + 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 + + The binding expression computes the value by reading other QProperty values. + Behind the scenes this dependency is tracked. Whenever a change in any property's + dependency is detected, the binding expression is re-evaluated and the new + result is applied to the property. For example: + + \code + QProperty<QString> firstname("John"); + QProperty<QString> lastname("Smith"); + QProperty<int> age(41); + + QProperty<QString> fullname; + fullname.setBinding([&]() { return firstname.value() + " " + lastname.value() + " age: " + QString::number(age.value()); }); + + qDebug() << fullname.value(); // Prints "John Smith age: 41" + + firstname = "Emma"; // Triggers binding reevaluation + + qDebug() << fullname.value(); // Prints the new value "Emma Smith age: 41" + + // Birthday is coming up + age.setValue(age.value() + 1); // Triggers re-evaluation + + qDebug() << fullname.value(); // Prints "Emma Smith age: 42" + \endcode + + When a new value is assigned to the \c firstname property, the binding + expression for \c fullname is reevaluated. So when the last \c qDebug() statement + tries to read the name value of the \c fullname property, the new value is returned. + + Since bindings are C++ functions, they may do anything that's possible + in C++. This includes calling other functions. If those functions access values + held by QProperty, they automatically become dependencies to the binding. + + Binding expressions may use properties of any type, so in the above example the age + is an integer and folded into the string value using conversion to integer, but + the dependency is fully tracked. + + \section1 Bindable Property Getters and Setters + + When a class has a bindable property, either using QProperty + or QObjectBindableProperty, special care has to be taken when formulating + getters and setters for that property. + + \section2 Bindable Property Getters + + To ensure proper operation of the automatic dependency-tracking system, + every possible code path in a getter needs to read from the underlying + property object. + In addition, the property must not be written inside the getter. + Design patterns which recompute or refresh anything in the getter + are not compatible with bindable properties. + + It is therefore recommended to only use trivial getters with bindable properties. + + \section2 Bindable Property Setters + + To ensure proper operation of the automatic dependency-tracking system, + every possible code path in a setter needs to write to the underlying + property object, even if the value did not change. + + Any other code in a setter has a high propability of being incorrect. + Any code doing updates based on the new value is most likely a bug, + as this code won't be executed when the property is changed + through a binding. + + It is therefore recommended to only use trivial setters with bindable properties. + + \section1 Writing to a Bindable Property + + Bindable properties inform their dependent properties about each change. + This might trigger change handlers, which in turn might call arbitrary code. + Thus, every write to a bindable property has to be inspected carefully. + The following problems might occur. + + \section2 Writing Intermediate Values to Bindable Properties + + Bindable properties must not be used as variables in algorithms. Each value written + would be communicated to dependent properties. + For example, in the following code, other properties that depend on + \b myProperty would be first informed about the change to \b 42, then about + the change to \b maxValue. + + \badcode + myProperty = somecomputation(); // returning, say, 42 + if (myProperty.value() > maxValue) + myProperty = maxValue; + \endcode + + Instead, perform the computation in a separate variable. Correct usage is shown in the + following example. + + \code + int newValue = someComputation(); + if (newValue > maxValue) + newValue = maxValue; + myProperty = newValue; // only write to the property once + \endcode + + \section2 Writing Bindable Properties in Transitional States + + When a bindable property is a member of a class, each write to that property + might expose the current state to the outside. So bindable properties must + not be written in transient states, when class invariants are not met. + + For example, in a class representing a circle which holds two members + \b radius and \b area consistent, a setter might look like this (where radius + is a bindable property): + + \badcode + void setRadius(double newValue) + { + radius = newValue; // this might trigger change handlers + area = M_PI * radius * radius; + emit radiusChanged(); + } + \endcode + + Here, code triggered in change handlers might use the circle, while it has + the new radius, but still the old area. + + \section1 Bindable Properties with Virtual Setters and Getters + + Property setters and getters should normally be minimal and do nothing but + setting the property; hence it is not normally appropriate for such setters + and getters to be virtual. There is nothing it makes sense for the derived + class to do. + + However some Qt classes can have properties with virtual setters. When + subclassing such a Qt class, overriding such setters requires special care. + + In any case the base implementation \e must be called for the binding to + work correctly. + + The following illustrates this approach. + + \badcode + void DerivedClass::setValue(int val) + { + // do something + BaseClass::setValue(val); + // probably do something else + } + \endcode + + All the common rules and recommendations regarding writing to bindable + properties also apply here. As soon as the base class implementation is + called, all the observers are notified about the change to the property. + This means that class invariants must be met before calling the base + implementation. + + In the rare case where such virtual getters or setters are necessary, the + base class should document the requirements it imposes on overrides. + + \section1 Formulating a Property Binding + + Any C++ expression evaluating to the correct type can be used as a binding + expression and be given to the setBinding() method. However, to formulate + a correct binding, some rules must be followed. + + Dependency tracking only works on bindable properties. It's the developer's + responsibility to ensure that all properties used in the binding expression + are bindable properties. When non-bindable properties are used in a binding + expression, changes to those properties do not trigger updates to the bound + property. No warning or error is generated either at compile-time or at run-time. + The bound property will be updated only when bindable properties used in the + binding expression are changed. + Non-bindable properties might be used in a binding if it's possible + to ensure that markDirty is called on the property being bound on each + change of the non-bindable dependency. + + The bound property might evaluate its binding several times during its lifetime. + The developer must make sure that all objects used in the binding expression + live longer than the binding. + + The bindable property system is not thread-safe. Properties used in the binding + expression on one thread must not be read or modified by any other thread. + An object of a QObject-derived class which has a property with a binding must + not be moved to a different thread. + Also, an object of a QObject-derived class which has a property which is used + in a binding must not be moved to a different thread. In this context, it's + irrelevant whether it's used in a binding of a property in the same object + or in a binding of a property in another object. + + The binding expression should not read from the property it's a binding for. Otherwise, + an evaluation loop exists. + + The binding expression must not write to the property it's a binding for. + + Functions used as bindings as well as all code which is called inside a binding + must not co_await. Doing so can confuse the property system's tracking of dependencies. + + \section1 Bindable Properties and Multithreading + + Bindable properties are not threadsafe, unless stated otherwise. + A bindable property must not be read or modified by any thread other than + the one is was created in. + + \section1 Tracking Bindable Properties + + Sometimes the relationships between properties cannot be expressed using + bindings. Instead you may need to run custom code whenever the value of a property + changes and instead of assigning the value to another property, pass it to + other parts of your application. For example writing data into a network socket + or printing debug output. QProperty provides two mechanisms for tracking. + + You can register for a callback function to be called whenever the value of + a property changes, by using onValueChanged(). If you want the callback to also + be called for the current value of the property, register your callback using + subscribe() instead. + + \section1 Interaction with Q_PROPERTYs + + A \l {The Property System}{Q_PROPERTY} that defines \c BINDABLE can be bound and + used in binding expressions. You can implement such properties using \l {QProperty}, + \l {QObjectBindableProperty}, or \l {QObjectComputedProperty}. + + 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 \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 53b34fe120..3d7685447f 100644 --- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc +++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc @@ -1,35 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \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 @@ -72,7 +48,7 @@ \li QObject::inherits() function returns whether an object is an instance of a class that inherits a specified class within the QObject inheritance tree. - \li QObject::tr() and QObject::trUtf8() translate strings for + \li QObject::tr() translates strings for \l{Internationalization with Qt}{internationalization}. \li QObject::setProperty() and QObject::property() dynamically set and get properties by name. diff --git a/src/corelib/doc/src/objectmodel/object.qdoc b/src/corelib/doc/src/objectmodel/object.qdoc index 2dd2594ae4..7b6b840df0 100644 --- a/src/corelib/doc/src/objectmodel/object.qdoc +++ b/src/corelib/doc/src/objectmodel/object.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page object.html diff --git a/src/corelib/doc/src/objectmodel/objecttrees.qdoc b/src/corelib/doc/src/objectmodel/objecttrees.qdoc index 29e2393e57..8939a534d4 100644 --- a/src/corelib/doc/src/objectmodel/objecttrees.qdoc +++ b/src/corelib/doc/src/objectmodel/objecttrees.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page objecttrees.html diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index e3c506e8bc..99a3e60d88 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -1,35 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \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 @@ -68,14 +44,21 @@ specified. It is for reading the property value. Ideally, a const function is used for this purpose, and it must return either the property's type or a const reference to that type. e.g., QWidget::focus is a read-only - property with \c READ function, QWidget::hasFocus(). + property with \c READ function, QWidget::hasFocus(). If a \c BINDABLE is + specified, you can write \c{READ default} to have the \c READ accessor + generated from the \c BINDABLE. \li A \c WRITE accessor function is optional. It is for setting the property value. It must return void and must take exactly one argument, either of the property's type or a pointer or reference to that type. e.g., QWidget::enabled has the \c WRITE function QWidget::setEnabled(). Read-only properties do not need \c WRITE - functions. e.g., QWidget::focus has no \c WRITE function. + functions. e.g., QWidget::focus has no \c WRITE function. If you specify + both a \c BINDABLE and \c{WRITE default}, a \c WRITE accessor will be + generated from the \c BINDABLE. The generated \c WRITE accessor will \e not + explicitly emit any signal declared with \c NOTIFY. You should register + the signal as change handler to the \c BINDABLE, for example using + \l{Q_OBJECT_BINDABLE_PROPERTY}. \li A \c MEMBER variable association is required if no \c READ accessor function is specified. This makes the given member variable @@ -99,8 +82,9 @@ which must be of the same type as the property. The parameter will take the new value of the property. The \c NOTIFY signal should only be emitted when the property has really been changed, to avoid bindings being unnecessarily - re-evaluated in QML, for example. Qt emits automatically that signal when - needed for MEMBER properties that do not have an explicit setter. + re-evaluated in QML, for example. The signal is emitted automatically when + the property is changed via the Qt API (QObject::setProperty, + QMetaProperty, etc.), but not when the MEMBER is changed directly. \li A \c REVISION number or \c REVISION() macro is optional. If included, it defines the property and its notifier signal to be used in a particular @@ -109,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 @@ -131,6 +115,13 @@ editable property for (checkable) buttons. Note that QItemDelegate gets and sets a widget's \c USER property. + \li The \c {BINDABLE bindableProperty} attribute indicates that the + property supports \l {Qt Bindable Properties}{bindings}, + and that it is possible to set and inspect + bindings to this property via the meta object system (QMetaProperty). + \c bindableProperty names a class member of type QBindable<T>, where T + is the property type. This attribute was introduced in Qt 6.0. + \li The presence of the \c CONSTANT attribute indicates that the property value is constant. For a given object instance, the READ method of a constant property must return the same value every time it is called. This @@ -217,7 +208,10 @@ 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 @@ -283,10 +277,29 @@ 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 Like other meta-data, class information is accessible at run-time through the meta-object; see QMetaObject::classInfo() for details. + + \section1 Using Bindable Properties + + Three different types can be used to implement bindable properties: + \list + \li \l QProperty + \li \l QObjectBindableProperty + \li \l QObjectComputedProperty. + \endlist + The first one is a general class for bindable properties. The latter + two can only be used inside a \l QObject. + + For more information, including examples, see the classes mentioned above + and the general tips on implementing and using + \l {Qt Bindable Properties}{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 85fe4df2ce..f0eeb20048 100644 --- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc +++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page signalsandslots.html @@ -32,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 @@ -133,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 @@ -321,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 @@ -412,8 +386,12 @@ \section2 Using Qt with 3rd Party Signals and Slots It is possible to use Qt with a 3rd party signal/slot mechanism. - You can even use both mechanisms in the same project. Just add the - following line to your qmake project (.pro) file. + You can even use both mechanisms in the same project. To do that, + write the following into your CMake project file: + + \snippet code/doc_src_containers.cpp cmake_no_keywords + + In a qmake project (.pro) file, you need to write: \snippet code/doc_src_containers.cpp 22 @@ -423,4 +401,19 @@ with the \c{no_keywords} flag, simply replace all uses of the Qt moc keywords in your sources with the corresponding Qt macros Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT. -*/ + + \section2 Signals and slots in Qt-based libraries + + The public API of Qt-based libraries should use the keywords + \c{Q_SIGNALS} and \c{Q_SLOTS} instead of \c{signals} and + \c{slots}. Otherwise it is hard to use such a library in a project + that defines \c{QT_NO_KEYWORDS}. + + To enforce this restriction, the library creator may set the + preprocessor define \c{QT_NO_SIGNALS_SLOTS_KEYWORDS} when building + the library. + + This define excludes signals and slots without affecting whether + other Qt-specific keywords can be used in the library + implementation. + */ diff --git a/src/corelib/doc/src/plugin-classes.qdoc b/src/corelib/doc/src/plugin-classes.qdoc index 3becad48be..dab3e74e82 100644 --- a/src/corelib/doc/src/plugin-classes.qdoc +++ b/src/corelib/doc/src/plugin-classes.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group plugins diff --git a/src/corelib/doc/src/qt6-changes.qdoc b/src/corelib/doc/src/qt6-changes.qdoc index 21bbd499ed..011568ef75 100644 --- a/src/corelib/doc/src/qt6-changes.qdoc +++ b/src/corelib/doc/src/qt6-changes.qdoc @@ -1,33 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtcore-changes-qt6.html - \title Porting to Qt 6 - Qt Core + \title Changes to Qt Core + \ingroup changes-qt-5-to-6 + \brief Changes to containers, strings, serialization and I/O classes. Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use. @@ -46,7 +24,7 @@ \section3 qHash() Signature For custom types, QHash and QMultiHash rely on you providing - a \l{The qHash() hashing function} {custom qHash() function} + a \l{qHash}{custom qHash() function} in the same namespace. In Qt 4 and Qt 5, the return value and optional second argument of a \c qHash function was of type \c uint. In Qt 6, it is \c size_t. @@ -68,12 +46,12 @@ \section3 Stability of References - The implementation of QHash and QMultiHash in Qt 6 got changed from + The implementation of QHash, QMultiHash and QSet in Qt 6 got changed from a node based approach to a two stage lookup table. This design allows to keep the memory overhead of a hash instance very small, while at the same time giving good performance. - One behavioral change to note is that the new QHash implementation + One behavioral change to note is that the new implementation will not provide stable references to elements in the hash when the table needs to grow, or when entries are removed. Applications that rely on such stability might now run into undefined behavior. @@ -85,4 +63,572 @@ In Qt 6, both types and use cases are distinct, and QHash::insertMulti got removed. + + \section2 QVector, QList + + Prior to Qt 6, QVector and QList were separate classes. In Qt 6, they are + unified: Qt 5 QList implementation is gone and both classes use updated + QVector implementation instead. QList is the class with the actual + implementation and QVector is an alias (typedef) to QList. + + QList's fromVector() and toVector(), and QVector's fromList() and toList(), + no longer involve data copying in Qt 6. They now return the object that they + were called for. + + \section3 API Changes + + QList's (and hence QVector's) size type is changed from \c int to \c + qsizetype. Together with the size type, all relevant methods' signatures are + updated to use \c qsizetype. This allows QList to hold more than 2^31 items + on 64 bit platforms. + + When upgrading the code base to Qt 6, this API change would most likely + result in compiler warnings about narrowing type conversions. Having the + following example code: + + \code + void myFunction(QList<MyType> &data) { + int size = data.size(); + // ... + const int pos = getInsertPosition(size); + data.insert(pos, MyType()); + // ... + } + \endcode + + you would need to update it to use either \c qsizetype or an auto keyword: + + \code + void myFunction(QList<MyType> &data) { + auto size = data.size(); + // ... + const auto pos = getInsertPosition(size); + data.insert(pos, MyType()); + // ... + } + \endcode + + Alternatively, you may use type casting and cast everything to \c int or to + \c qsizetype. + + \note If you want to build against both Qt 5 and Qt 6, the auto keyword is a + good solution to cover signature differences between the versions. + + \section3 Memory Layout + + QList received multiple changes related to the memory layout in Qt 6. + + In Qt 5, \c{sizeof(QList<T>)} was equal to a size of a pointer. Now, the + extra pointer indirection is removed and QList data members are directly + stored in the object. By default, expect \c{sizeof(QList<T>)} to be equal to + the size of 3 pointers. + + At the same time, memory layout of the elements is also updated. QList now + always stores its elements directly in the allocated memory region as + opposed to Qt 5, where certain objects were separately allocated on the heap + and pointers to the objects were placed into the QList instead. + + Note that the latter, in particular, affects large objects. To have Qt 5 + behavior, you could wrap your objects into smart pointers and store these + smart pointers in QList directly. In this case, the type of your QList would + be \c{QList<MySmartPointer<MyLargeObject>>} as opposed to + \c{QList<MyLargeObject>} in Qt 5. + + \section3 Stability of References + + There are several changes made to the QVector/QList implementation. The + QVector related one is: insertion at the beginning is optimized (similarly + to QList in Qt 5). The QList related one is: memory layout for the elements + is simplified. + + \important These changes impact the stability of references. In Qt 6, you + should consider any size or capacity modifying method to invalidate all + references, even when QList is not \l{Implicit Sharing}{implicitly shared}. + Exceptions to this rule are documented explicitly. + + Applications that rely on certain reference stability might run into + undefined behavior when upgraded to use Qt 6. You should pay extra attention + to cases where QVector or QList with a non C-compatible array layout were + used originally. + + \section1 View classes in Qt6 + + \section2 General Overview + + There are several new \c View classes coming with Qt6. There is the already + existing \l QStringView, now accompanied by \l QByteArrayView and followed + by a specialized \l QUtf8StringView and a more universal \l QAnyStringView. + + \section2 Introduction to view classes on the example of QStringView + + The QStringView class provides a unified view on UTF-16 strings with a + read-only subset of the QString API. Unlike QString, which keeps its own + copy of the string (possibly ref-counted), QStringView provides a view of + a string that is stored elsewhere. + + \code + char hello[]{ "Hello." }; // narrow multi-byte string literal + QString str{hello}; // needs to make a copy of the string literal + QString strToStr(str); // atomic increment involved to not create a copy of hello again + + // The above code can be re-written to avoid copying and atomic increment. + + QStringView view{ u"Hello." }; // view to UTF-16 encoded string literal + QStringView viewToView{ view }; // view of the same UTF-16 encoded string literal + \endcode + + The string \c "Hello." is stored in the binary and is not allocated at + run-time. \c view is only a view onto the string \c "Hello.", therefore + no copy has to be created. When we copy a QStringView, the \c viewToView + observes the same string as the copied-from \c view is observing. This + means that \c viewToView does not need to create a copy or an atomic + increment. They are views onto the existing string \c "Hello.". + + \section2 Views as function argument + + Views should be passed by value, not by reference-to-const. + + \code + void myfun1(QStringView sv); // preferred + void myfun2(const QStringView &sv); // compiles and works, but slower + \endcode + + \section2 View manipulation functions + + QStringView supports functions that let us manipulate the view of the + string. This allows us to change the view without creating a partial copy + of the viewed string. + + \code + QString pineapple = "Pineapple"; + QString pine = pineapple.left(4); + + // The above code can be re-written to avoid creating a partial copy. + + QStringView pineappleView{ pineapple }; + QStringView pineView = pineappleView.left(4); + \endcode + + \section2 Non null-terminated strings and strings containing \c {'\0'} + + QStringView supports both null-terminated and non null-terminated strings. + The difference comes from the way you initialize the QStringView: + + \code + QChar aToE[]{ 'a', 'b', 'c', 'd', 'e' }; + + QStringView nonNull{ aToE, std::size(aToE) }; // with length given + QStringView nonNull{ aToE }; // automatically determines the length + + QChar fToJ[]{ 'f', 'g', 'h', '\0', 'j' }; + + // uses given length, doesn't search for '\0', so '\0' at position 3 + // is considered to be a part of the string similarly to 'h' and 'j + QStringView nonNull{ fToJ, std::size(fToJ) }; + QStringView part{ fToJ }; //stops on the first encounter of '\0' + \endcode + + \section2 Ownership model of views + + As \c views do not own the memory they reference, care must be taken to + ensure that the referenced data (for example, owned by a \l QString) + outlives the \c view on all code paths. + + \badcode + QStringView sayHello() + { + QString hello("Hello."); + return QStringView{ hello }; // hello gets out of scope and destroyed + } + + void main() + { + QStringView hello{ sayHello() }; + qDebug() << hello; // undefined behavior + } + \endcode + + \section2 Converting an QStringView to QString + + QStringView will not implicitly or explicitly convert to a QString, but can + create a deep copy of its data: + + \code + void print(const QString &s) { qDebug() << s; } + + void main() + { + QStringView string{ u"string"}; + + // print(string); // invalid, no implicit conversion + // QString str{ string }; // invalid, no explicit conversion + + print(string.toString()); + QString str = string.toString(); // create QString from view + } + \endcode + + \section2 Important notes + + By leveraging the new view classes, one can achieve a lot of performance + boost in many use cases. However, it is important to know that there might + be some caveats. Therefore it is important to remember: + + \list + \li Views should be passed by value, not by reference-to-const. + \li Constructing a view with a negative length is undefined behavior. + \li Care must be taken to ensure that the referenced data (for example, + owned by a \l QString) outlives the view on all code paths. + \endlist + + \section1 String related classes + + \section2 The QStringView class + + Starting with Qt6 it is generally recommended to use \l QStringView over + \c QStringRef. \l QStringView references a contiguous portion of a UTF-16 + string it does not own. It acts as an interface type to all kinds of UTF-16 + strings, without the need to construct a \l QString first. The \l QStringView + class exposes almost all read-only methods of \l QString and the previously + existing \c QStringRef class. + + \note Care must be taken to ensure that the referenced string data (for + example, owned by a \l QString) outlives the \l QStringView on all code paths. + + \note If a \l QStringView wraps a \l QString, care needs to be taken since + unlike \c QStringRef \l QStringView will not update the internal data pointer + once the \l QString data relocates. + + \code + QString string = ...; + QStringView view{string}; + + // Appending something very long might cause a relocation and will + // ultimately result in a garbled QStringView. + string += ...; + \endcode + + \section2 The QStringRef class + + In Qt6 \l QStringRef got removed from Qt Core. To ease porting of existing + applications without touching the whole code-base, the \c QStringRef class + did not vanish completely and instead it got moved into the Qt5Compat module. + If you want to use \c QStringRef further, see \l {Using the Qt5Compat module}. + + Unfortunately, some methods exposed by \l QString returning a \c QStringRef, + could not be moved to Qt5Compat. Therefore some manual porting may be + needed. If your code uses one or more of the following functions you need to + port them to use \l QStringView or \l QStringTokenizer. It is also + recommended to use \l {QStringView::tokenize} over \l {QStringView::split} + for performance critical code. + + Change code using \c QStringRef: + \code + QString string = ...; + QStringRef left = string.leftRef(n); + QStringRef mid = string.midRef(n); + QStringRef right = string.rightRef(n); + + QString value = ...; + const QVector<QStringRef> refs = string.splitRef(' '); + if (refs.contains(value)) + return true; + \endcode + + to: + + \code + QString string = ...; + QStringView left = QStringView{string}.left(n); + QStringView mid = QStringView{string}.mid(n); + QStringView right = QStringView{string}.right(n); + + QString value = ...; + const QList<QStringView> refs = QStringView{string}.split(u' '); + if (refs.contains(QStringView{value})) + return true; + // or + const auto refs = QStringView{string}.tokenize(u' '); + for (auto ref : refs) { + if (ref == value) + return true; + } + \endcode + + \section1 QMutex and Related Classes + + In Qt 6, QRecursiveMutex does not inherit from QMutex anymore. This change was + done to improve the performance of both QMutex and QRecursiveMutex. + + Due to those changes, the QMutex::RecursionMode enum has been removed, and + QMutexLocker is now a templated class that can operate on both QMutex and + QRecursiveMutex. + + \section1 QFuture and Related Classes + + \section2 The QFuture class + + To avoid unintended usage of QFuture, there were some changes to + QFuture API in Qt 6, which may introduce source compatibility breaks. + + \section3 Implicit conversions between QFuture and other types + + Conversion of \c QFuture<T> to \c T has been disabled. The casting + operator was calling QFuture::result(), which may lead to undefined + behavior if the user has moved the results from QFuture via + QFuture::takeResult() before trying to do the conversion. Use + QFuture::result() or QFuture::takeResult() methods explicitly, + where you need to convert \c QFuture<T> to \c T. + + The implicit conversion from \c QFuture<T> to \c QFuture<void> has + been also disabled. If you really intend to do the conversion, use the + explicit \c {QFuture<void>(const QFuture<T> &)} constructor: + + \code + QFuture<int> future = ... + QFuture<void> voidFuture = QFuture<void>(future); + \endcode + + \section3 Equality operators + + The equality operators of QFuture have been removed. They were comparing + the underlying d-pointers instead of comparing the results, which is not + what users might expect. If you need to compare QFuture objects, use + \c QFuture::result() or \c QFuture::takeResult() methods. For example: + + \code + QFuture<int> future1 = ...; + QFuture<int> future2 = ...; + if (future1.result() == future2.result()) + // ... + \endcode + + \section2 Behavioral Changes to QFuture and QFutureWatcher + + In Qt 6, there were some improvements to QFuture and QFutureWatcher which + caused the following behavioral changes: + + \list + + \li After pausing QFuture or QFutureWatcher (by calling \c pause() or + \c setPaused(true)), QFutureWatcher will not immediately stop delivering + progress and result ready signals. At the moment of pausing there may be + still computations that are in progress and cannot be stopped. Signals + for such computations may be still delivered after pause, instead of being + postponed and reported only after next resume. To get notified when pause + actually took effect, QFutureWatcher::suspended() signal can be used. In + addition, there are new \c isSuspending() and \c isSuspended() methods, + to check if the QFuture is in the process of suspending or it's already in + the suspended state. Note that for consistency reasons, for both QFuture + and QFutureWatcher the pause-related APIs were deprecated and replaced by + similar methods having "suspend" in the name instead. + + \li QFuture::waitForFinished() will now wait until QFuture is actually in + the finished state, instead of exiting as soon as it is not in the running + state. This prevents \c waitForFinished() from exiting immediately, if at + the moment of calling it the future is not started yet. The same applies to + QFutureWatcher::waitForFinished(). This change won't affect the behavior of + code that was using QFuture with QtConcurrent. Only the code that was using + it with the undocumented \c QFutureInterface may be affected. + + \li QFutureWatcher::isFinished() now reflects the finished-state of the + QFuture rather than returning false until QFutureWatcher::finished() has + been emitted. + + \endlist + + \section2 The QPromise class + + In Qt 6, the new QPromise class should be used instead of unofficial + QFutureInterface as a "setter" counterpart of QFuture. + + \section1 IO Classes + + \section2 The QProcess class + + In Qt 6, the QProcess::start() overload that interprets a single command string + by splitting it into program name and arguments is renamed to QProcess::startCommand(). + However, a QProcess::start() overload that takes a single string, as well as a QStringList + for arguments exists. Since the QStringList parameter defaults to the empty list, existing + code only passing a string will still compile, but will fail to execute the process if it + is a complete command string that includes arguments. + + Qt 5.15 introduced deprecation warnings for the respective overload to make it easy to + discover and update existing code: + + \code + QProcess process; + + // compiles with warnings in 5.15, compiles but fails with Qt 6 + process.start("dir \"My Documents\""); + + // works with both Qt 5 and Qt 6; also see QProcess::splitCommand() + process.start("dir", QStringList({"My Documents"}); + + // works with Qt 6 + process.startCommand("dir \"My Documents\""); + \endcode + + QProcess::pid() and the Q_PID type have been removed; use QProcess::processId() instead to + get the native process identifier. Code using native Win32 APIs to access the data in the + Q_PID as a Win32 \c{PROCESS_INFORMATION} struct is no longer supported. + + \section1 Meta-Type system + + \section2 The QVariant class + + \c QVariant has been rewritten to use \c QMetaType for all of its operations. This implies + behavior changes in a few methods: + + \list + + \li \c QVariant::isNull() now only returns \c true if the \c QVariant is empty or contains a + \c nullptr. In Qt 5, it also returned true for classes in qtbase which had an \c isNull method + themselves if that one returned true. Code relying on the old behavior needs to check whether + the contained value returns isNull – however such code is unlikely to occur in practice, as + \c isNull() is rarely the property one is interested in (compare \c QString::isEmpty() / \c isNull() + and \c QTime::isValid / \c isNull). + + \li \c QVariant::operator== uses \c QMetaType::equals in Qt 6. Therefore, some graphical + types like \c QPixmap, \c QImage and \c QIcon will never compare equal. Moreover, floating + point numbers stored in \c QVariant are no longer compared with \c qFuzzyCompare, but instead + use exact comparisons. + + \endlist + + Furthermore, QVariant::operator<, QVariant::operator<=, QVariant::operator> and + QVariant::operator>= were removed, because different variants are not always orderable. This + also means that QVariant cannot be used anymore as a key in a QMap. + + \section2 The QMetaType class + + In Qt 6, registration of comparators, and QDebug and QDataStream streaming operators is + done automatically. Consequently, \c QMetaType::registerEqualsComparator(), + \c QMetaType::registerComparators(), \c qRegisterMetaTypeStreamOperators() and + \c QMetaType::registerDebugStreamOperator() do no longer exist. Calls to those methods + have to be removed when porting to Qt 6. + + \section2 Type registration + + Types used in \c Q_PROPERTY have their meta-type stored in the class' \c QMetaObject. This + requires the types to be complete when moc sees them, which can lead to compilation errors + in code that worked in Qt 5. There are three ways to fix this issue: + + \list + + \li Include the header which defines the type. + \li Instead of using an include, use the \c Q_MOC_INCLUDE macro. This helps if including the header + would cause a cyclic dependency, or when it would slow down compilation. + \li If the header is present in the cpp file which implements the class, it is also possible to include + the moc generated file there. + + \endlist + + \section1 Regular expression classes + + \section2 The QRegularExpression class + + In Qt 6, the \c QRegExp type has been retired to the Qt5Compat module + and all Qt APIs using it have been removed from other modules. + Client code which used it can be ported to use \l QRegularExpression + in its place. As \l QRegularExpression is present already in Qt 5, + this can be done and tested before migration to Qt 6. + + \include corelib/port-from-qregexp.qdocinc porting-to-qregularexpression + + \section2 The QRegExp class + + In Qt6 \l QRegExp got removed from Qt Core. If your application cannot be + ported right now, \c QRegExp still exists in Qt5Compat to keep these + code-bases working. If you want to use \c QRegExp further, see + \l {Using the Qt5Compat module}. + + \section1 QEvent and subclasses + + The QEvent class defined a copy constructor and an assignment operator, + in spite of being a polymorphic class. Copying classes with virtual methods + can result in slicing when assigning objects from different classes to each + other. Since copying and assigning often happens implicilty, this could + lead to hard-to-debug problems. + + In Qt 6, the copy constructor and assignment operator for QEvent subclasses + have been made protected to prevent implicit copying. If you need to copy + events, use the \l{QEvent::}{clone} method, which will return a heap-allocated + copy of the QEvent object. Make sure you delete the clone, perhaps using + std::unique_ptr, unless you post it (in which case Qt will delete it once it + has been delivered). + + In your QEvent subclasses, override clone(), and declare the protected and + default-implemented copy constructor and assignment operator like this: + + \code + class MyEvent : public QEvent + { + public: + // ... + + MyEvent *clone() const override { return new MyEvent(*this); } + + protected: + MyEvent(const MyEvent &other) = default; + MyEvent &operator=(const MyEvent &other) = default; + MyEvent(MyEvent &&) = delete; + MyEvent &operator=(MyEvent &&) = delete; + // member data + }; + \endcode + + Note that if your MyEvent class allocates memory (e.g. through a + pointer-to-implementation pattern), then you will have to implement + custom copy semantics. + + \section1 Serialization classes + + In Qt 6, QJsonDocument methods for converting it to/from Qt's legacy + JSON binary format were removed in favor of the standardized CBOR format. + Qt JSON types can be converted to Qt CBOR types, which can in turn be + serialized into the CBOR binary format and vice versa. See, for example, + \l QCborValue::fromJsonValue() and \l QCborValue::toJsonValue(). + + If you still need to use the binary JSON format, you can use the + replacements provided in the Qt5Compat module. They can be found in the + \l QBinaryJson namespace. See \l {Using the Qt5Compat module} to find out + how to use the module in your application. + + \section1 Other classes + + In Qt 5, QCoreApplication::quit() was equivalent to calling + \l{QCoreApplication::exit()}. This just exited the main event loop. + + In Qt 6, the method will instead try to close all top-level windows by posting + a close event. The windows are free to cancel the shutdown process by + ignoring the event. + + Call QCoreApplication::exit() to keep the non-conditional behavior. + + QLibraryInfo::location() and QLibraryInfo::Location were deprecated due to inconsistent + naming. Use the new API QLibraryInfo::path() and QLibraryInfo::LibraryPath instead. + + \section1 Qt State Machine Framework + + \l {Qt State Machine} was moved into the Qt SCXML module (soon to be renamed to Qt + State Machines) and therefore it is no longer part of Qt Core. There were very few + cross dependencies inside Qt Core which ultimately led to this decision. + + \section1 Using the Qt5Compat module + + To use the \l {Qt 5 Core Compatibility APIs}{Qt5Compat} module, you need + to build with its headers in your include path and link against its library. + If you are using \l qmake, add the following to your \c .pro file: + + \code + QT += core5compat + \endcode + + If you build your application or library using \l {Build with CMake}{cmake}, + add the following to your \c CMakeList.txt: + \code + PUBLIC_LIBRARIES + Qt::Core5Compat + \endcode */ diff --git a/src/corelib/doc/src/qtcore-index.qdoc b/src/corelib/doc/src/qtcore-index.qdoc index 34a4446ccc..38452e1b2b 100644 --- a/src/corelib/doc/src/qtcore-index.qdoc +++ b/src/corelib/doc/src/qtcore-index.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtcore-index.html @@ -31,16 +7,15 @@ \brief The Qt Core module is part of Qt's essential modules. - \section1 Core Functionalities - Qt Core adds these features to C++: + The Qt Core module adds these features to C++: \list \li a very powerful mechanism for seamless object communication called signals and slots \li queryable and designable object properties - \li hierarchical and queryable object trees that organize - \li object ownership in a natural way with guarded pointers (QPointer) + \li hierarchical and queryable object trees that organize object ownership + in a natural way with guarded pointers (QPointer) \li a dynamic cast that works across library boundaries \endlist @@ -53,14 +28,17 @@ \li \l{Signals & Slots} \endlist - \include module-use.qdocinc using qt module - \quotefile overview/using-qt-core.cmake + \section1 Using the Module - See also the \l{Build with CMake} overview. + \include {module-use.qdocinc} {using the c++ api} + + \section2 Building with CMake + + \include {module-use.qdocinc} {building with cmake} {Core} \section2 Building with qmake - If you use \l qmake to build your projects, Qt5Core is linked by default. + If you use \l qmake to build your projects, Qt Core is linked by default. \section1 Threading and Concurrent Programming @@ -97,15 +75,38 @@ \list \li \l{The Animation Framework} \li \l{JSON Support in Qt} - \li \l{The State Machine Framework} + \li \l{CBOR Support in Qt} + \li \l{Inter-Process Communication} \li \l{How to Create Qt Plugins} \li \l{The Event System} + \li \l{Application Permissions} + \endlist + + \section1 Reference + + \list + \li \l{Qt Core C++ Classes}{C++ Classes} + \list + \li \l{Animation Framework}{Animation Classes} + \li \l{Threading Classes} + \li \l{Container Classes} + \li \l{Plugin Classes} + \li \l{Implicitly Shared Classes} + \li \l{Input/Output and Networking}{Input/Output Classes} + \li \l{Event Classes} + \endlist + \li CMake API + \list + \li \l{CMake Commands in Qt6 Core}{CMake Commands} + \li \l{CMake Variables in Qt6 Core}{CMake Variables} + \li \l{CMake Target Properties in Qt6 Core}{CMake Target Properties} + \endlist \endlist \section1 Module Evolution - \l{Porting to Qt 6 - Qt Core} lists important changes in the module API - and functionality that were done for the Qt 6 series of Qt. + \l{Changes to Qt Core} lists important changes in the module API + and functionality that were made for the Qt 6 series of Qt. \section1 Licenses and Attributions @@ -116,29 +117,12 @@ See \l{Qt Licensing} for further details. Executables on Windows potentially link - against \l{The qtmain Library}. This library is available + against \l{The QtEntryPoint Library}. This library is available under commercial licenses and also under the \l{BSD 3-clause "New" or "Revised" License}. Furthermore, Qt Core in Qt \QtVersion may contain third party - modules under following permissive licenses: + modules under the following permissive licenses: \generatelist{groupsbymodule attributions-qtcore} - - \section1 Reference - These are links to the API reference materials. - \list - \li \l{Qt Core C++ Classes}{C++ Classes} - \list - \li \l{Animation Framework}{Animation Classes} - \li \l{Threading Classes} - \li \l{Container Classes} - \li \l{Plugin Classes} - \li \l{Implicitly Shared Classes} - \li \l{State Machine Classes} - \li \l{Input/Output and Networking}{Input/Output Classes} - \li \l{Event Classes} - \endlist - \endlist - */ diff --git a/src/corelib/doc/src/qtcore.qdoc b/src/corelib/doc/src/qtcore.qdoc index 70b14e755a..a46add1342 100644 --- a/src/corelib/doc/src/qtcore.qdoc +++ b/src/corelib/doc/src/qtcore.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtCore @@ -35,4 +11,24 @@ \brief Provides core non-GUI functionality. All other Qt modules rely on this module. + + The \l{Qt Core} page contains information about how to use the module. +*/ + +/*! + \module QtCorePrivate + \title Qt Core Private C++ Classes + \qtvariable core-private + \preliminary + \brief Provides private core functionality. + +//! [qtcoreprivate-usage] + When building with CMake, use the following commands to use + private Qt Core APIs: + + \badcode + find_package(Qt6 REQUIRED COMPONENTS Core) + target_link_libraries(mytarget PRIVATE Qt6::CorePrivate) + \endcode +//! [qtcoreprivate-usage] */ diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc new file mode 100644 index 0000000000..14ee5e7a9c --- /dev/null +++ b/src/corelib/doc/src/qtserialization.qdoc @@ -0,0 +1,145 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtserialization.html + \title Qt Serialization + \brief Serializations provided by Qt API + + The purpose of serialization is to save the state of an object to be able to + recreate it when needed. It allows you to perform actions like: + + \list + \li Sending the object to a remote application by using a web service + \li Passing the object as a JSON or XML string + \li Saving and restoring user information or sharing it across applications + \endlist + + The Qt API provides support for serialization for several use cases: + + \list + \li \l JSON support in Qt provides an easy to use C++ API to parse, modify + and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form + of binary data encoding that is a superset of JSON. + \li \l QDataStream provides serialization of binary data to a QIODevice + \li \l {Qt XML C++ Classes} provide C++ implementations of the \l {XML Streaming} + and DOM standards for XML + \li \l CBOR is Qt's implementation for the CBOR serialization format. + \li \l QSettings provides a way of serializing and storing platform independent + application settings. + \endlist + + \section1 Advantages of JSON and CBOR + + When you use \l JSON information is stored in a QJsonObject and a QJsonDocument + takes care to stream values into a QByteArray. + + For example + \code + QJsonObject jobject; + jobject["SensorID"] = m_id; + jobject["AmbientTemperature"] = m_ambientTemperature; + jobject["ObjectTemperature"] = m_objectTemperature; + jobject["AccelerometerX"] = m_accelerometerX; + jobject["AccelerometerY"] = m_accelerometerY; + jobject["AccelerometerZ"] = m_accelerometerZ; + jobject["Altitude"] = m_altitude; + jobject["Light"] = m_light; + jobject["Humidity"] = m_humidity; + QJsonDocument doc( jobject ); + + return doc.toJson(); + \endcode + + JSON has several advantages: + + \list + \li Textual JSON is declarative, which makes it readable to humans + \li The information is structured + \li Exchanging generic information is easy + \li JSON allows extending messages with additional values + \li Many solutions exist to receive and parse JSON in cloud-based solutions + \endlist + + \l CBOR is the Concise Binary Object Representation, a very compact form of + binary data encoding that is a superset of JSON. It was created by the IETF + Constrained RESTful Environments (CoRE) WG, which has been used in many new + RFCs. CBOR shares many of the advantages of JSON, but sacrifices human + readability for compactness. + + \section1 Advantages of QDataStream Classes + + \l QDataStream is a viable option when the whole flow of data is determined + and not about to change. In addition, both the reader and the writer of the + data must be written in Qt. + + Adding support for this to a class requires two additional operators. + For example, for a class named SensorInformation: + + \code + QDataStream &operator<<(QDataStream &, const SensorInformation &); + QDataStream &operator>>(QDataStream &, SensorInformation &); + \endcode + + The implementation for the serialization is shown below: + + \code + QDataStream &operator<<(QDataStream &out, const SensorInformation &item) + { + QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision(); + out.setFloatingPointPrecision(QDataStream::DoublePrecision); + out << item.m_id + << item.m_ambientTemperature + << item.m_objectTemperature + << item.m_accelerometerX + << item.m_accelerometerY + << item.m_accelerometerZ + << item.m_altitude + << item.m_light + << item.m_humidity; + out.setFloatingPointPrecision(prev); + return out; + } + \endcode + + Deserialization works similarly, but using the \c {>>} operator. + For example, \c {out >> item.m_id}, and so on. + + Usually, using QDataStream is faster than using textual JSON. + + \section1 Advantages of Qt XML C++ Classes + + Qt provides both DOM classes and stream-based classes to read and write + XML content. + + Qt provides the QDomDocument class that represents the XML document and + two classes for reading and writing the XML through a simple streaming API: + QXmlStreamReader and QXmlStreamWriter. + + \section2 The DOM XML Classes + + QDomDocument class represents the entire XML document. It is the root of the + document tree and provides primary access to the document's data. + + \section2 The Stream-Based XML Classes + + A stream reader reports an XML document as a stream of tokens. This differs + from SAX as SAX applications provide handlers to receive XML events from the + parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the + reader when they are needed. This pulling approach makes it possible to build + recursive descent parsers, allowing XML parsing code to be split into + different methods or classes. + + QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed + entities. Hence, data provided to the stream reader adheres to the + W3C's criteria for well-formed XML, or an error will be raised. Functions + such as \c atEnd(), \c error(), and \c hasError() can be used to test for + such errors and obtain a description of them. + + The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces, + when the namespaceUri is specified when writing elements or attributes. + + \section1 Classes that Provide Serialization + + \annotatedlist qtserialization +*/ diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc index 9b80c31b00..7c7613c9b8 100644 --- a/src/corelib/doc/src/resource-system.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -1,115 +1,219 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page resources.html \title The Qt Resource System - \brief A platform-independent mechanism for storing binary files in an application. + \brief A platform-independent mechanism for shipping resource files in an + application. \keyword resource system - The Qt resource system is a platform-independent mechanism for - storing binary files in the application's executable. This is - useful if your application always needs a certain set of files - (icons, translation files, etc.) and you don't want to run the - risk of losing the files. + The Qt resource system is a platform-independent mechanism for shipping + resource files in an application. Use it if your application always needs a + certain set of files (like icons, translation files, images), and you don't + want to use system-specific means to package and locate these resources. - The resource system is based on tight cooperation between \l qmake, - \l rcc (Qt's resource compiler), and QFile. + 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}{external resource file}. - \section1 Resource Collection Files (\c{.qrc}) + The resource system is based on tight cooperation between Qt's \l rcc + resource compiler, the build system, and the Qt runtime API. + + \note Currently, the Qt resource system does not make use of any + system-specific capabilities for handling resources, such as the ones on + Windows, \macos, and iOS. This might change in a future Qt release. + + \section1 The Qt Resource Compiler (rcc) + + The \l{Resource Compiler (rcc)} command line tool reads resource files and + generates either a C++ or Python source file, or an \c .rcc file. + + The list of files and related metadata is passed to \c rcc in the form of a + \l{Qt Resource Collection File}. + + By default, rcc will generate C++ source code that is then compiled as part + of an executable or library. The \c{-g python} option generates Python + source code instead. The \c -binary option generates a binary archive that + is by convention saved in an \c .rcc file and can be loaded at runtime. + + \note While it is possible to run \c rcc from the command line, this is + typically best left to a build system. See also the sections about + \l{qmake} and \l{CMake} below. + + \section1 Qt Resource Collection File (.qrc) + \target {Qt Resource Collection File} \target {Resource Collection Files} - The resources associated with an application are specified in a - \c .qrc file, an XML-based file format that lists files on the - disk and optionally assigns them a resource name that the - application must use to access the resource. + A \c .qrc file is an XML document that enumerates local files to be + included as runtime resources. It serves as input to \c{rcc}. Here's an example \c .qrc file: \quotefile resource-system/application.qrc - The resource files listed in the \c .qrc file are files that are - part of the application's source tree. The specified paths are - relative to the directory containing the \c .qrc file. Note that - the listed resource files must be located in the same directory as - the \c .qrc file, or one of its subdirectories. - - Resource data can either be compiled into the binary and thus accessed - immediately in application code, or a binary resource can be created - and at a later point in application code registered with the resource - system. - - By default, resources are accessible in the application under the - same file name as they have in the source tree, with a \c :/ prefix, - or by a \l{QUrl}{URL} with a \c qrc scheme. - - For example, the file path \c :/images/cut.png or the URL - \c qrc:///images/cut.png would give access to the - \c cut.png file, whose location in the application's source tree - is \c images/cut.png. This can be changed using the \c file tag's + 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 + the \c .qrc file. + + The path is also used by default to identify the file's content at runtime. + That is, the file \c titlebarLeft.png will be available in the resource system as + \c{:/res/titlebarLeft.png} or \c{qrc:/res/titlebarLeft.png}. + To override this default run-time name, see \l{Prefixes} and \l{Aliases}. + + \e{Qt Creator}, \e{Qt Design Studio}, \QD, and \e{Qt Visual Studio Tools} + allow you to create, inspect and edit \c .qrc files through a convenient + user interface. Except for \QD, they also provide wizards for projects + using the Qt resource system. + + \section1 Build System Integration + + The processing of resource files with \c rcc is typically done at the time + the application is built. Several build tools have dedicated support for + this, including \l CMake and \l qmake. + + \section2 CMake + + If \c CMAKE_AUTORCC is enabled, you can just add \c .qrc files as sources + to your executable or library. The referenced resource files will then be + embedded into the binary: + + \snippet resource-system/CMakeLists.txt AUTORCC + + See \l {https://cmake.org/cmake/help/latest/prop_tgt/AUTORCC.html} + {CMake's AUTORCC documentation} for more details about AUTORCC. + + An alternative to AUTORCC is using Qt6Core's CMake function + \l qt_add_resources, which gives more control over the creation of + resources. For example, it allows you to specify the content of the + resource directly in the project file without writing a \c .qrc file first: + + \snippet resource-system/CMakeLists.txt qt_add_resources + + Finally, \l qt_add_qml_module allows you to embed Qt Quick resources into + the resource system of your application. The function is defined in the + \c Qml component of the \c Qt6 CMake package. + + \section2 qmake + + \l{qmake Manual}{qmake} supports handing resources with the \l{RESOURCES} + 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/application.pro qrc + + This creates a resource of several \c{.png} files, that are addressable + like this: \c{":/res/titlebarLeft.png"}. + + If the directory layout of the files you want to embed into the resource + doesn't match the expectations of the application, you can specify + \c{resources.base}. \c base is a path prefix that denotes the root point of + the file's alias. In the example above, if \c{resources.base} is set to + \c{"res"}, then \c{titlebarLeft.png} is addressable as \c{":/titlebarLeft.png"}. + + \section1 Runtime API + + Qt API that deals with iterating and reading files has built-in support for + the Qt Resource System. You can pass a resource path instead of a local + file path to QFile and QDir, but also for instance to the QIcon, QImage, and + QPixmap constructors: + + \snippet resource-system/mainwindow.cpp 21 + + The \c : prefix makes it explicit that "/images/cut.png" should be loaded + from the Qt Resource System. + + You can also reference the Qt resource system through a QUrl. Use the + \c qrc scheme in this case: + + \snippet resource-system/main.cpp url + + \section1 Advanced Topics + + \section2 Prefixes + + A \c .qrc file can set a prefix to be added to each local file name, given + in a \c <file> element, to get the name by which the file shall be known + within the resource system. + + Prefixes allow you to structure the resources, avoiding clashes between + resource files added through different \c .qrc files in different libraries + or plugins. + + \note The \c /qt and \c /qt-project.org prefixes are reserved for documented + use cases in Qt. The \l{Using qt.conf}{qt.conf} file is for instance looked + up in \c{:/qt/etc/qt.conf} or \c{qrc:/qt/etc/qt.conf}. + + \section2 Aliases + + Sometimes it is convenient to make a resource file available under a + different path at runtime. \c .qrc files allow this by setting an \c alias attribute: \snippet code/doc_src_resources.qdoc 0 - The file is then accessible as \c :/cut-img.png from the - application. It is also possible to specify a path prefix for all - files in the \c .qrc file using the \c qresource tag's \c prefix - attribute: + The file is from the application then only accessible as \c :/cut-img.png + or \c{qrc:/cut-img.png}. + + \section2 Discarding the file contents + + Sometimes you want to add a file node to the resource file system but + don't actually want to add the file contents. \c .qrc files allow this + by setting the \c empty attribute to \c{true}. + + \snippet code/doc_src_resources.qdoc 4 - \snippet code/doc_src_resources.qdoc 1 + The resulting file is then still accessible from the application, but + its contents are empty. - In this case, the file is accessible as \c - :/myresources/cut-img.png. + This is useful to strip QML source code from an application binary. - Some resources need to change based on the user's locale, - such as translation files or icons. This is done by adding a \c lang - attribute to the \c qresource tag, specifying a suitable locale - string. For example: + \note If you omit the QML source code from the binary, the QML engine has to + rely on the compilation units created by \l{qmlcachegen} or \l{qmlsc}. + Those are tied to the specific version of Qt they were built with. If you + change the version of Qt your application uses, they can't be loaded + anymore. + + \section2 Language Selectors + + Some resources need to change based on the user's locale, such as + translation files or icons. \l{Resource Collection Files} support this + through a \c lang attribute to the \c qresource tag, specifying a suitable + locale string. For example: \snippet code/doc_src_resources.qdoc 2 - If the user's locale is French (i.e., QLocale::system().name() returns - "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg - image. For other locales, \c cut.jpg is used. + If the user's locale is French (i.e., QLocale::system().language() is + French), \c :/cut.jpg or \c qrc:/cut.jpg becomes a reference to the + \c cut_fr.jpg image. For other locales, \c cut.jpg is used. - See the QLocale documentation for a description of the format to use - for locale strings. + See the QLocale documentation for a description of the format to use for + locale strings. See QFileSelector for an additional mechanism to select locale-specific - resources, in addition to the ability to select OS-specific and other - features. + resources. + + \section2 Embedding Large Files + + By default, \c rcc embeds the resource files into executables in the form + of C++ arrays. This can be problematic especially for large resources. - \section2 External Binary Resources + If the compiler takes too long, or even fails because of memory overflow, + you can opt into a special mode where the resources are embedded as part of + a two-step process. The C++ compiler only reserves enough space in the + target executable or library for the resources. The actual embedding of the + resource file's content and metadata is then done after the compilation and + linking phase, through another rcc call. - For an external binary resource to be created you must create the resource - data (commonly given the \c .rcc extension) by passing the -binary switch to - \l rcc. Once the binary resource is created you can register the resource - with the QResource API. + For CMake, you need to use the \l{qt_add_big_resources} function. + + \section2 External Resource Files + + An alternative to embedding the resource files into the binary is to store + them in a separate \c .rcc file. \c rcc allows this with the \c -binary + option. Such a \c .rcc file must then be loaded at runtime with QResource. For example, a set of resource data specified in a \c .qrc file can be compiled in the following way: @@ -120,46 +224,27 @@ \snippet code/doc_src_resources.cpp 4 - \section2 Compiled-In Resources - - For a resource to be compiled into the binary the \c .qrc file must be - mentioned in the application's \c .pro file so that \c qmake knows - about it. For example: - - \snippet resource-system/application.pro 0 + If you use CMake, you can use the \l{qt_add_binary_resources} function + to schedule the \c rcc call above: - \c qmake will produce make rules to generate a file called \c - qrc_application.cpp that is linked into the application. This - file contains all the data for the images and other resources as - static C++ arrays of compressed binary data. The \c - qrc_application.cpp file is automatically regenerated whenever - the \c .qrc file changes or one of the files that it refers to - changes. If you don't use \c .pro files, you can either invoke - \c rcc manually or add build rules to your build system. + \snippet resource-system/CMakeLists.txt qt_add_binary_resources - \image resources.png Building resources into an application + \section2 Resources in a Qt for Python application - Currently, Qt always stores the data directly in the executable, - even on Windows, \macos, and iOS, where the operating system provides - native support for resources. This might change in a future Qt - release. - - \section2 Resources in a Qt for Python application - - The resource collection file is converted to a Python module by using - the resource compiler \l rcc: + The resource collection file is converted to a Python module by using the + resource compiler \l rcc: \code - rcc -g python application.qrc > application_rc.py + rcc -g python mainwindow.qrc > mainwindow_rc.py \endcode - The module needs to be imported in the application: + The module can then be imported in the application: \code - import application_rc.py + import mainwindow_rc.py \endcode - \section1 Compression + \section2 Compression \c rcc attempts to compress the content to optimize disk space usage in the final binaries. By default, it will perform a heuristic check to determine @@ -176,7 +261,7 @@ The default value is "70", indicating that the compressed file must be 70% smaller than the original (no more than 30% of the original file size). - It is possible to turn off compression, if desired. This can be useful if + It is possible to turn off compression if desired. This can be useful if your resources already contain a compressed format, such as \c .png files, and you do not want to incur the CPU cost at build time to confirm that it can't be compressed. Another reason is if disk usage is not a problem and @@ -209,25 +294,25 @@ levels: \list - \li \c{best}: use the best algorithm among the ones below, at its highest + \li \c best: use the best algorithm among the ones below, at its highest compression level, to achieve the most compression at the expense of using a lot of CPU time during compilation. This value is useful in the XML file to indicate a file should be most compressed, regardless of which algorithms \c rcc supports. - \li \c{zstd}: use the \l{https://zstd.net}{Zstandard} library to compress + \li \c zstd: use the \l{Zstandard Site}{Zstandard} library to compress contents. Valid compression levels range from 1 to 19, 1 is least compression (least CPU time) and 19 is the most compression (most CPU - time). The default level is 14. A special value of 0 tells the \c{zstd} + time). The default level is 14. A special value of 0 tells the \c zstd library to choose an implementation-defined default. - \li \c{zlib}: use the \l{https://zlib.net}{zlib} library to compress + \li \c zlib: use the \l{https://zlib.net}{zlib} library to compress contents. Valid compression levels range from 1 to 9, with 1 applying the least compression (least CPU time) and 9 the most compression (most CPU time). The special value 0 means "no compression" and should not be used. The default is implementation-defined, but usually is level 6. - \li \c{none}: no compression. This is the same as the \c{-no-compress} + \li \c none: no compression. This is the same as the \c -no-compress option. \endlist @@ -236,67 +321,27 @@ that library will result in an error. The default compression algorithm is \c zstd if it is enabled, \c zlib if not. - \section1 Using Resources in the Application - - In the application, resource paths can be used in most places - instead of ordinary file system paths. In particular, you can - pass a resource path instead of a file name to the QIcon, QImage, - or QPixmap constructor: - - \snippet resource-system/mainwindow.cpp 21 - - See the \l{mainwindows/application}{Application} example for an - actual application that uses Qt's resource system to store its - icons. - - In memory, resources are represented by a tree of resource - objects. The tree is automatically built at startup and used by - QFile for resolving paths to resources. You can use a QDir initialized - with ":/" to navigate through the resource tree from the root. - - Qt's resources support the concept of a search path list. If you then - refer to a resource with \c : instead of \c :/ as the prefix, the - resource will be looked up using the search path list. The search - path list is empty at startup; call QDir::addSearchPath() to - add paths to it. + \section2 Explicit Loading and Unloading of Embedded Resources - \section1 Using Resources in a Library + Resources embedded in C++ executable or library code are automatically + registered to the Qt resource system in a constructor of an internal + global variable. Since the global variables are initialized before + main() runs, the resources are available when the program starts to + run. - If you have resources in a library, you need to force initialization - of your resources by calling \l Q_INIT_RESOURCE() with the base name - of the \c .qrc file. For example: + When embedding resources in \e{static} libraries, the C++ linker might + remove the static variables that register the resources. If you + embed resources in a static library, you therefore need to explicitly + register your resources by calling \l Q_INIT_RESOURCE() with the base + name of the \c .qrc file. + For example: \snippet code/doc_src_resources.cpp 5 - This ensures that the resources are linked into the final application - binary in the case of static linking. You should put the initialization - code close to where the resources are used in your library, so that - clients of your library will only link in the resources if they use - the feature of the library that depends on them. + You can also explicitly remove registered resources from the application, + for instance when unloading a plugin. Use \l Q_CLEANUP_RESOURCE() for this. Note: As the resource initializers generated by rcc are declared in the - global namespace, your calls to \l Q_INIT_RESOURCE() also need to be done - outside of any namespace. - - If the library includes resources that are not used internally, but - instead exposed to clients of the library, the initialization needs - to happen in the application code. For example: - - \snippet code/doc_src_resources.cpp 6 - - As before, this ensures that the resources are linked into the final - application binary in the case of static linking, but also triggers - loading of the library in the case of dynamic linking, such as plugins. - - Similarly, if you must unload a set of resources explicitly - (because a plugin is being unloaded or the resources are not valid - any longer), you can force removal of your resources by calling - \l Q_CLEANUP_RESOURCE() with the same base name as above. - - \note The use of \l Q_INIT_RESOURCE() and \l Q_CLEANUP_RESOURCE() is - not necessary in the following cases: - \list - \li When the resource is built as part of the application. - \li When the resource is built with CMake as part of a static library. - \endlist + global namespace, your calls to \l Q_INIT_RESOURCE() and + \l Q_CLEANUP_RESOURCE() need to be done outside any namespace. */ diff --git a/src/corelib/doc/src/statemachine.qdoc b/src/corelib/doc/src/statemachine.qdoc deleted file mode 100644 index 881a0785c6..0000000000 --- a/src/corelib/doc/src/statemachine.qdoc +++ /dev/null @@ -1,577 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group statemachine - \brief How to create and execute state graphs. - \title State Machine Classes - - These \l{Qt Core} classes are part of the \l{The State Machine Framework}{ - State Machine Framework}. - -*/ - -/*! - \page statemachine-api.html - \title The State Machine Framework - \brief An overview of the State Machine framework for constructing and executing state graphs. - - \ingroup frameworks-technologies - - \tableofcontents - - The State Machine framework provides classes for creating and executing - state graphs. The concepts and notation are based on those from Harel's - \l{http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf}{Statecharts: A visual formalism for complex systems}, which - is also the basis of UML state diagrams. The semantics of state machine - execution are based on \l{State Chart XML: State Machine Notation for - Control Abstraction}{State Chart XML (SCXML)}. - - Statecharts provide a graphical way of modeling how a system reacts to - stimuli. This is done by defining the possible \e states that the system can - be in, and how the system can move from one state to another (\e transitions - between states). A key characteristic of event-driven systems (such as Qt - applications) is that behavior often depends not only on the last or current - event, but also the events that preceded it. With statecharts, this - information is easy to express. - - The State Machine framework provides an API and execution model that can be - used to effectively embed the elements and semantics of statecharts in Qt - applications. The framework integrates tightly with Qt's meta-object system; - for example, transitions between states can be triggered by signals, and - states can be configured to set properties and invoke methods on {QObject}s. - Qt's event system is used to drive the state machines. - - The state graph in the State Machine framework is hierarchical. States can be nested inside of - other states, and the current configuration of the state machine consists of the set of states - which are currently active. All the states in a valid configuration of the state machine will - have a common ancestor. - - \sa {The Declarative State Machine Framework} - - \section1 Classes in the State Machine Framework - - These classes are provided by qt for creating event-driven state machines. - - \annotatedlist statemachine - - \section1 A Simple State Machine - - To demonstrate the core functionality of the State Machine API, let's look - at a small example: A state machine with three states, \c s1, \c s2 and \c - s3. The state machine is controlled by a single QPushButton; when the button - is clicked, the machine transitions to another state. Initially, the state - machine is in state \c s1. The statechart for this machine is as follows: - - \image statemachine-button.png - \omit - \caption This is a caption - \endomit - - The following snippet shows the code needed to create such a state machine. - First, we create the state machine and states: - - \snippet statemachine/main.cpp 0 - - Then, we create the transitions by using the QState::addTransition() - function: - - \snippet statemachine/main.cpp 1 - - Next, we add the states to the machine and set the machine's initial state: - - \snippet statemachine/main.cpp 2 - - Finally, we start the state machine: - - \snippet statemachine/main.cpp 3 - - The state machine executes asynchronously, i.e. it becomes part of your - application's event loop. - - \section1 Doing Useful Work on State Entry and Exit - - The above state machine merely transitions from one state to another, it - doesn't perform any operations. The QState::assignProperty() function can be - used to have a state set a property of a QObject when the state is - entered. In the following snippet, the value that should be assigned to a - QLabel's text property is specified for each state: - - \snippet statemachine/main.cpp 4 - - When any of the states is entered, the label's text will be changed - accordingly. - - The QState::entered() signal is emitted when the state is entered, and the - QState::exited() signal is emitted when the state is exited. In the - following snippet, the button's \l {QPushButton::}{showMaximized()} slot - will be called when state \c s3 is entered, and the button's \l {QPushButton::}{showMinimized()} - slot will be called when \c s3 is exited: - - \snippet statemachine/main.cpp 5 - - Custom states can reimplement QAbstractState::onEntry() and - QAbstractState::onExit(). - - \section1 State Machines That Finish - - The state machine defined in the previous section never finishes. In order - for a state machine to be able to finish, it needs to have a top-level \e - final state (QFinalState object). When the state machine enters a top-level - final state, the machine will emit the QStateMachine::finished() signal and - halt. - - All you need to do to introduce a final state in the graph is create a - QFinalState object and use it as the target of one or more transitions. - - \section1 Sharing Transitions By Grouping States - - Assume we wanted the user to be able to quit the application at any time by - clicking a Quit button. In order to achieve this, we need to create a final - state and make it the target of a transition associated with the Quit - button's \l{QPushButton::}{clicked()} signal. We could add a transition from each of \c s1, \c - s2 and \c s3; however, this seems redundant, and one would also have to - remember to add such a transition from every new state that is added in the - future. - - We can achieve the same behavior (namely that clicking the Quit button quits - the state machine, regardless of which state the state machine is in) by - grouping states \c s1, \c s2 and \c s3. This is done by creating a new - top-level state and making the three original states children of the new - state. The following diagram shows the new state machine. - - \image statemachine-button-nested.png - \omit - \caption This is a caption - \endomit - - The three original states have been renamed \c s11, \c s12 and \c s13 to - reflect that they are now children of the new top-level state, \c s1. Child - states implicitly inherit the transitions of their parent state. This means - it is now sufficient to add a single transition from \c s1 to the final - state \c s2. New states added to \c s1 will also automatically inherit this - transition. - - All that's needed to group states is to specify the proper parent when the - state is created. You also need to specify which of the child states is the - initial one (i.e. which child state the state machine should enter when the - parent state is the target of a transition). - - \snippet statemachine/main2.cpp 0 - - \snippet statemachine/main2.cpp 1 - - In this case we want the application to quit when the state machine is - finished, so the machine's \l {QStateMachine::}{finished()} signal is connected to the - application's \l {QCoreApplication::}{quit()} slot. - - A child state can override an inherited transition. For example, the - following code adds a transition that effectively causes the Quit button to - be ignored when the state machine is in state \c s12. - - \snippet statemachine/main2.cpp 2 - - A transition can have any state as its target, i.e. the target state does - not have to be on the same level in the state hierarchy as the source state. - - \section1 Using History States to Save and Restore the Current State - - Imagine that we wanted to add an "interrupt" mechanism to the example - discussed in the previous section; the user should be able to click a button - to have the state machine perform some non-related task, after which the - state machine should resume whatever it was doing before (i.e. return to the - old state, which is one of \c s11, \c s12 and \c s13 in this case). - - Such behavior can easily be modeled using \e{history states}. A history - state (QHistoryState object) is a pseudo-state that represents the child - state that the parent state was in the last time the parent state was - exited. - - A history state is created as a child of the state for which we wish to - record the current child state; when the state machine detects the presence - of such a state at runtime, it automatically records the current (real) - child state when the parent state is exited. A transition to the history - state is in fact a transition to the child state that the state machine had - previously saved; the state machine automatically "forwards" the transition - to the real child state. - - The following diagram shows the state machine after the interrupt mechanism - has been added. - - \image statemachine-button-history.png - \omit - \caption This is a caption - \endomit - - The following code shows how it can be implemented; in this example we - simply display a message box when \c s3 is entered, then immediately return - to the previous child state of \c s1 via the history state. - - \snippet statemachine/main2.cpp 3 - - \section1 Using Parallel States to Avoid a Combinatorial Explosion of States - - Assume that you wanted to model a set of mutually exclusive properties of a - car in a single state machine. Let's say the properties we are interested in - are Clean vs Dirty, and Moving vs Not moving. It would take four mutually - exclusive states and eight transitions to be able to represent and freely - move between all possible combinations. - - \image statemachine-nonparallel.png - \omit - \caption This is a caption - \endomit - - If we added a third property (say, Red vs Blue), the total number of states - would double, to eight; and if we added a fourth property (say, Enclosed vs - Convertible), the total number of states would double again, to 16. - - Using parallel states, the total number of states and transitions grows - linearly as we add more properties, instead of exponentially. Furthermore, - states can be added to or removed from the parallel state without affecting - any of their sibling states. - - \image statemachine-parallel.png - \omit - \caption This is a caption - \endomit - - To create a parallel state group, pass QState::ParallelStates to the QState - constructor. - - \snippet statemachine/main3.cpp 0 - - When a parallel state group is entered, all its child states will be - simultaneously entered. Transitions within the individual child states - operate normally. However, any of the child states may take a transition which exits the parent - state. When this happens, the parent state and all of its child states are exited. - - The parallelism in the State Machine framework follows an interleaved semantics. All parallel - operations will be executed in a single, atomic step of the event processing, so no event can - interrupt the parallel operations. However, events will still be processed sequentially, since - the machine itself is single threaded. As an example: Consider the situation where there are two - transitions that exit the same parallel state group, and their conditions become true - simultaneously. In this case, the event that is processed last of the two will not have any - effect, since the first event will already have caused the machine to exit from the parallel - state. - - \section1 Detecting that a Composite State has Finished - - A child state can be final (a QFinalState object); when a final child state - is entered, the parent state emits the QState::finished() signal. The - following diagram shows a composite state \c s1 which does some processing - before entering a final state: - - \image statemachine-finished.png - \omit - \caption This is a caption - \endomit - - When \c s1 's final state is entered, \c s1 will automatically emit - \l {QState::}{finished()}. We use a signal transition to cause this event to trigger a - state change: - - \snippet statemachine/main3.cpp 1 - - Using final states in composite states is useful when you want to hide the - internal details of a composite state; i.e. the only thing the outside world - should be able to do is enter the state, and get a notification when the - state has completed its work. This is a very powerful abstraction and - encapsulation mechanism when building complex (deeply nested) state - machines. (In the above example, you could of course create a transition - directly from \c s1 's \c done state rather than relying on \c s1 's - \l {QState::}{finished()} signal, but with the consequence that implementation details of - \c s1 are exposed and depended on). - - For parallel state groups, the QState::finished() signal is emitted when \e - all the child states have entered final states. - - \section1 Targetless Transitions - - A transition need not have a target state. A transition without a target can - be triggered the same way as any other transition; the difference is that - when a targetless transition is triggered, it doesn't cause any state - changes. This allows you to react to a signal or event when your machine is - in a certain state, without having to leave that state. Example: - - \code - QStateMachine machine; - QState *s1 = new QState(&machine); - - QPushButton button; - QSignalTransition *trans = new QSignalTransition(&button, &QPushButton::clicked); - s1->addTransition(trans); - - QMessageBox msgBox; - msgBox.setText("The button was clicked; carry on."); - QObject::connect(trans, QSignalTransition::triggered, &msgBox, &QMessageBox::exec); - - machine.setInitialState(s1); - \endcode - - The message box will be displayed each time the button is clicked, but the - state machine will remain in its current state (s1). If the target state - were explicitly set to s1, however, s1 would be exited and re-entered each - time (e.g. the QAbstractState::entered() and QAbstractState::exited() - signals would be emitted). - - \section1 Events, Transitions and Guards - - A QStateMachine runs its own event loop. For signal transitions - (QSignalTransition objects), QStateMachine automatically posts a - QStateMachine::SignalEvent to itself when it intercepts the corresponding - signal; similarly, for QObject event transitions (QEventTransition objects) - a QStateMachine::WrappedEvent is posted. - - You can post your own events to the state machine using - QStateMachine::postEvent(). - - When posting a custom event to the state machine, you typically also have - one or more custom transitions that can be triggered from events of that - type. To create such a transition, you subclass QAbstractTransition and - reimplement QAbstractTransition::eventTest(), where you check if an event - matches your event type (and optionally other criteria, e.g. attributes of - the event object). - - Here we define our own custom event type, \c StringEvent, for posting - strings to the state machine: - - \snippet statemachine/main4.cpp 0 - - Next, we define a transition that only triggers when the event's string - matches a particular string (a \e guarded transition): - - \snippet statemachine/main4.cpp 1 - - In the \l {QAbstractTransition::}{eventTest()} reimplementation, we first check if the event type is the - desired one; if so, we cast the event to a \c StringEvent and perform the - string comparison. - - The following is a statechart that uses the custom event and transition: - - \image statemachine-customevents.png - \omit - \caption This is a caption - \endomit - - Here's what the implementation of the statechart looks like: - - \snippet statemachine/main4.cpp 2 - - Once the machine is started, we can post events to it. - - \snippet statemachine/main4.cpp 3 - - An event that is not handled by any relevant transition will be silently - consumed by the state machine. It can be useful to group states and provide - a default handling of such events; for example, as illustrated in the - following statechart: - - \image statemachine-customevents2.png - \omit - \caption This is a caption - \endomit - - For deeply nested statecharts, you can add such "fallback" transitions at - the level of granularity that's most appropriate. - - \section1 Using Restore Policy To Automatically Restore Properties - - In some state machines it can be useful to focus the attention on assigning properties in states, - not on restoring them when the state is no longer active. If you know that a property should - always be restored to its initial value when the machine enters a state that does not explicitly - give the property a value, you can set the global restore policy to - QStateMachine::RestoreProperties. - - \code - QStateMachine machine; - machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); - \endcode - - When this restore policy is set, the machine will automatically restore all properties. If it - enters a state where a given property is not set, it will first search the hierarchy of ancestors - to see if the property is defined there. If it is, the property will be restored to the value - defined by the closest ancestor. If not, it will be restored to its initial value (i.e. the - value of the property before any property assignments in states were executed.) - - Take the following code: - - \snippet statemachine/main5.cpp 0 - - Lets say the property \c fooBar is 0.0 when the machine starts. When the machine is in state - \c s1, the property will be 1.0, since the state explicitly assigns this value to it. When the - machine is in state \c s2, no value is explicitly defined for the property, so it will implicitly - be restored to 0.0. - - If we are using nested states, the parent defines a value for the property which is inherited by - all descendants that do not explicitly assign a value to the property. - - \snippet statemachine/main5.cpp 2 - - Here \c s1 has two children: \c s2 and \c s3. When \c s2 is entered, the property \c fooBar - will have the value 2.0, since this is explicitly defined for the state. When the machine is in - state \c s3, no value is defined for the state, but \c s1 defines the property to be 1.0, so this - is the value that will be assigned to \c fooBar. - - \section1 Animating Property Assignments - - The State Machine API connects with the Animation API in Qt to allow automatically animating - properties as they are assigned in states. - - Say we have the following code: - - \snippet statemachine/main5.cpp 3 - - Here we define two states of a user interface. In \c s1 the \c button is small, and in \c s2 - it is bigger. If we click the button to transition from \c s1 to \c s2, the geometry of the button - will be set immediately when a given state has been entered. If we want the transition to be - smooth, however, all we need to do is make a QPropertyAnimation and add this to the transition - object. - - \snippet statemachine/main5.cpp 4 - - Adding an animation for the property in question means that the property assignment will no - longer take immediate effect when the state has been entered. Instead, the animation will start - playing when the state has been entered and smoothly animate the property assignment. Since we - do not set the start value or end value of the animation, these will be set implicitly. The - start value of the animation will be the property's current value when the animation starts, and - the end value will be set based on the property assignments defined for the state. - - If the global restore policy of the state machine is set to QStateMachine::RestoreProperties, - it is possible to also add animations for the property restorations. - - \section1 Detecting That All Properties Have Been Set In A State - - When animations are used to assign properties, a state no longer defines the exact values that a - property will have when the machine is in the given state. While the animation is running, the - property can potentially have any value, depending on the animation. - - In some cases, it can be useful to be able to detect when the property has actually been assigned - the value defined by a state. - - Say we have the following code: - - \snippet statemachine/main5.cpp 5 - - When \c button is clicked, the machine will transition into state \c s2, which will set the - geometry of the button, and then pop up a message box to alert the user that the geometry has - been changed. - - In the normal case, where animations are not used, this will operate as expected. However, if - an animation for the \c geometry of \c button is set on the transition between \c s1 and \c s2, - the animation will be started when \c s2 is entered, but the \c geometry property will not - actually reach its defined value before the animation is finished running. In this case, the - message box will pop up before the geometry of the button has actually been set. - - To ensure that the message box does not pop up until the geometry actually reaches its final - value, we can use the state's \l {QState::}{propertiesAssigned()} signal. The \l {QState::}{propertiesAssigned()} signal will be - emitted when the property is assigned its final value, whether this is done immediately or - after the animation has finished playing. - - \snippet statemachine/main5.cpp 6 - - In this example, when \c button is clicked, the machine will enter \c s2. It will remain in state - \c s2 until the \c geometry property has been set to \c QRect(0, 0, 50, 50). Then it will - transition into \c s3. When \c s3 is entered, the message box will pop up. If the transition into - \c s2 has an animation for the \c geometry property, then the machine will stay in \c s2 until the - animation has finished playing. If there is no such animation, it will simply set the property and - immediately enter state \c s3. - - Either way, when the machine is in state \c s3, you are guaranteed that the property \c geometry - has been assigned the defined value. - - If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit - the \l {QState::}{propertiesAssigned()} signal until these have been executed as well. - - \section1 What Happens If A State Is Exited Before The Animation Has Finished - - If a state has property assignments, and the transition into the state has animations for the - properties, the state can potentially be exited before the properties have been assigned to the - values defines by the state. This is true in particular when there are transitions out from the - state that do not depend on the \l {QState::}{propertiesAssigned()} signal, as described in the previous section. - - The State Machine API guarantees that a property assigned by the state machine either: - \list - \li Has a value explicitly assigned to the property. - \li Is currently being animated into a value explicitly assigned to the property. - \endlist - - When a state is exited prior to the animation finishing, the behavior of the state machine depends - on the target state of the transition. If the target state explicitly assigns a value to the - property, no additional action will be taken. The property will be assigned the value defined by - the target state. - - If the target state does not assign any value to the property, there are two - options: By default, the property will be assigned the value defined by the state it is leaving - (the value it would have been assigned if the animation had been permitted to finish playing). If - a global restore policy is set, however, this will take precedence, and the property will be - restored as usual. - - \section1 Default Animations - - As described earlier, you can add animations to transitions to make sure property assignments - in the target state are animated. If you want a specific animation to be used for a given property - regardless of which transition is taken, you can add it as a default animation to the state - machine. This is in particular useful when the properties assigned (or restored) by specific - states is not known when the machine is constructed. - - \code - QState *s1 = new QState(); - QState *s2 = new QState(); - - s2->assignProperty(object, "fooBar", 2.0); - s1->addTransition(s2); - - QStateMachine machine; - machine.setInitialState(s1); - machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar")); - \endcode - - When the machine is in state \c s2, the machine will play the default animation for the - property \c fooBar since this property is assigned by \c s2. - - Note that animations explicitly set on transitions will take precedence over any default - animation for the given property. - - \section1 Nesting State Machines - - QStateMachine is a subclass of QState. This allows for a state machine to be a child state of - another machine. QStateMachine reimplements QState::onEntry() and calls QStateMachine::start(), - so that when the child state machine is entered, it will automatically start running. - - The parent state machine treats the child machine as an \e atomic state in the state machine - algorithm. The child state machine is self-contained; it maintains its own event queue and - configuration. In particular, note that the \l{QStateMachine::}{configuration()} - of the child machine is not part of the parent machine's configuration (only the child machine - itself is). - - States of the child state machine cannot be specified as targets of transitions in the parent - state machine; only the child state machine itself can. Conversely, states of the parent state - machine cannot be specified as targets of transitions in the child state machine. The child - state machine's \l{QState::}{finished}() signal can be used to trigger a transition - in the parent machine. -*/ diff --git a/src/corelib/doc/src/timers.qdoc b/src/corelib/doc/src/timers.qdoc index 1fa62a6afb..dc205a47b9 100644 --- a/src/corelib/doc/src/timers.qdoc +++ b/src/corelib/doc/src/timers.qdoc @@ -1,46 +1,22 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page timers.html \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 @@ -55,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 GUI 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 this widget so that, - when this widget 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/wiggly}{Wiggly} - example shows how to use QBasicTimer. + and handle the timeout there. */ |
