diff options
Diffstat (limited to 'src/corelib/doc/src/includes')
-rw-r--r-- | src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc | 13 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc (renamed from src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.cmake) | 6 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc | 6 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies-deploy-tool-options.qdocinc | 20 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc | 12 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc | 4 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc | 16 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/cmake-generate-deploy-app-script.qdocinc | 21 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/models.qdocinc | 14 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/permissions.qdocinc | 51 | ||||
-rw-r--r-- | src/corelib/doc/src/includes/qstring.qdocinc | 36 |
11 files changed, 190 insertions, 9 deletions
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.cmake b/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc index 2f18622ecf..47133f6d10 100644 --- a/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.cmake +++ b/src/corelib/doc/src/includes/cmake-android-qt-finalize-project-warning.qdocinc @@ -1,6 +1,8 @@ -# Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +// 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-deploy-modified-variable-values.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc index 6c1f20adb2..632ddf756f 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-modified-variable-values.qdocinc @@ -2,8 +2,11 @@ cmake_minimum_required(VERSION 3.16...3.22) project(MyThings) +# The following CMAKE_INSTALL_*DIR variables are used to initialize their +# QT_DEPLOY_*_DIR counterparts. set(CMAKE_INSTALL_BINDIR "mybindir") set(CMAKE_INSTALL_LIBDIR "mylibdir") +set(CMAKE_INSTALL_LIBEXECDIR "mylibexecdir") find_package(Qt6 REQUIRED COMPONENTS Core) qt_standard_project_setup() @@ -15,10 +18,13 @@ 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 index 3c7fb8d5ee..6d026d6301 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-runtime-dependencies.qdocinc @@ -23,13 +23,11 @@ endif() qt_add_executable(HelperApp helper.cpp) set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>") -# The following script must only be executed at install time -set(deploy_script "${CMAKE_CURRENT_BINARY_DIR}/deploy_MyApp.cmake") - -file(GENERATE OUTPUT ${deploy_script} CONTENT " -# Including the file pointed to by QT_DEPLOY_SUPPORT ensures the generated -# deployment script has access to qt_deploy_runtime_dependencies() -include(\"${QT_DEPLOY_SUPPORT}\") +# 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}\" diff --git a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc index c5a1a40356..27e04b5b08 100644 --- a/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc +++ b/src/corelib/doc/src/includes/cmake-deploy-var-usage.qdocinc @@ -1,2 +1,6 @@ This variable is defined by the script named by \l QT_DEPLOY_SUPPORT. It should only be used as part of deployment during installation or a post-build rule. + +\note This is a low-level deployment API variable, and should only be used in +advanced use-cases that are not covered by the higher-level API commands, like +\l{qt_generate_deploy_app_script}. diff --git a/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc new file mode 100644 index 0000000000..64c6b3e49f --- /dev/null +++ b/src/corelib/doc/src/includes/cmake-generate-deploy-app-script-deploy-tool-options.qdocinc @@ -0,0 +1,16 @@ +\badcode +set(deploy_tool_options_arg "") +if(APPLE) + set(deploy_tool_options_arg --hardened-runtime) +elseif(WIN32) + set(deploy_tool_options_arg --no-compiler-runtime) +endif() + +qt_generate_deploy_app_script( + TARGET MyApp + OUTPUT_SCRIPT deploy_script + NO_UNSUPPORTED_PLATFORM_ERROR + DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg} +) +install(SCRIPT ${deploy_script}) +\endcode diff --git a/src/corelib/doc/src/includes/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/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] |