summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc
Commit message (Collapse)AuthorAgeFilesLines
* Doc: Use \keyword for alternative name of CMake commandKai Köhne3 hours21-21/+21
| | | | | | | | | | \target will let the browser jump right below the title. Instead, open the page from the start. Pick-to: 6.5 Change-Id: Ia58664aa2696aca4f299d57b8dbaa9b6cda90f27 Reviewed-by: Pranta Ghosh Dastider <pranta.dastider@qt.io> Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* Docs:Android: Add docs notes about support for content UrisNicholas Bennett6 days2-0/+43
| | | | | | | | | | | Add some details about the support of Qt apis (QFile, QDir, QFileInfo) for Android content uris. Fixes: QTBUG-99664 Task-number: QTBUG-98974 Pick-to: 6.5 6.4 6.2 5.15 Change-Id: I4b884623702ccad116d47049e34ccddfe21f83ca Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
* Doc: Only list qt core classes in qt core io groupAndreas Eliasson7 days1-1/+1
| | | | | | | | | | | The group page for Qt core classes related to I/O include classes from other modules. Remove these classes from the group; it may confuse the reader. Fixes: QTBUG-110020 Pick-to: 6.5 6.4 6.2 5.15 Change-Id: If7df85523ce6b3aa09605bd89d9899ce308d2671 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* IPC: add native key support to QSystemSemaphoreThiago Macieira8 days1-2/+2
| | | | | | | | | | | And deprecate the non-native key support API. Qt 7 may not even store the old, non-native Qt. Documentation in a new commit, when the dust settles. Change-Id: I12a088d1ae424825abd3fffd171d2b549eeed040 Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* IPC: Long live QNativeIpcKey keyThiago Macieira8 days2-0/+489
| | | | | | | | | Common to both QSharedMemory and QSystemSemaphore, this will hold the native key and will replace the concept of non-native key in those classes. Change-Id: Id8d5e3999fe94b03acc1fffd171c03197aea6016 Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
* Documentation: Port code snippets to new connection syntaxFriedemann Kleint2023-01-111-1/+1
| | | | | | | Pick-to: 6.5 6.4 6.2 Task-number: PYSIDE-2182 Change-Id: I5f800cf3a4a7afefbc36a79372fc35449fa953f0 Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QUrl/doc: explain that the scheme-less URL is probably not intendedThiago Macieira2023-01-061-0/+8
| | | | | | | | | It is a valid URL reference, which is not what people may want. Fixes: QTBUG-109855 Pick-to: 6.4 6.5 Change-Id: I69ecc04064514f939896fffd173783ce2228c1d2 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Slow Deprecation of FILENAME_VARIABLE, replacement by OUTPUT_SCRIPTAmir Masoud Abdol2023-01-055-8/+8
| | | | | | | | | | | | | As discussed in the latest CMake API Review, we are deprecating the FILENAME_VARIABLE variable name everywhere, and replacing it with OUTPUT_SCRIPT. [ChangeLog][CMake] The FILENAME_VARIABLE option of qt_generate_deploy_script and qt_generate_deploy_app_script is now deprecated, use OUTPUT_SCRIPT option instead. Change-Id: Ic8be33eefbc48540166ea0fcf1d1948b052d4b8a Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
* QStringBuilder: document issues with using "auto" keywordAhmad Samir2023-01-011-0/+23
| | | | | | | | Cleanup QStringBuilder API docs. Task-number: QTBUG-104354 Change-Id: I00029c8f4bfdf35869396ac14d7d9ba0da34cdb5 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Use more documentation snippets for QString and its siblingsAhmad Samir2023-01-011-0/+24
| | | | | | Pick-to: 6.5 Change-Id: Ia569806b586923473f68b9fe1d98a3628ba46a58 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Doc: Remove incorrect CMake instructions for QtCore-privateTopi Reinio2022-12-221-3/+11
| | | | | | | | | | | Drop the use of \qtcmakepackage for the module page that results in incorrect instructions, and replace it with a snippet with the correct commands to use. Pick-to: 6.5 6.4 6.2 Fixes: QTBUG-109214 Change-Id: I936910ddb9e4118f931d85e4b096ad52006dcc32 Reviewed-by: Kai Köhne <kai.koehne@qt.io>
* CMake: Allow contents of resources to be replaced by empty filesUlf Hermann2022-12-173-0/+50
| | | | | | | | | | | | | | | This makes it possible to process QML files using qmlcachegen, and retain the file nodes in the resource file system, but remove their actual content from the binary. To do so, you need to mark your files with the QT_DISCARD_FILE_CONTENTS source file property. Fixes: QTBUG-87676 Fixes: QTBUG-103481 Fixes: QTBUG-102024 Fixes: QTBUG-102785 Change-Id: I93d5a2bfca1739ff1e0f74c8082eb8aa451b9815 Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io> Reviewed-by: hjk <hjk@qt.io>
* CMake: Deprecate some android public APIsAlexandru Croitor2022-12-153-3/+4
| | | | | | | | | | | | | | | | | | | | | | | Deprecate usage of: - qt_android_add_apk_target - qt_android_apply_arch_suffix - qt_android_generate_deployment_settings when used by user projects directly. Instead, projects should use qt_add_executable / qt_add_library. Show a deprecation warning when the commands are used directly. The deprecation warnings can be silenced using cmake's -Wno-deprecated command line option. To detect non-direct usage from inside our own function implementations, we set some target properties which are then read to decide whether to show the message. Pick-to: 6.5 Fixes: QTBUG-108508 Change-Id: Ib039cc5f3a01c2276173abb1e43f4eed216d0170 Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
* Doc: Ensure qt_policy has a titleKai Köhne2022-12-142-1/+4
| | | | | | | Pick-to: 6.5 Change-Id: Ia8319627943294b163b10c52e76fedeb3ce3e3b0 Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io> Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* Document the qt_add_plugin() options new in Qt 6.5 as suchKai Köhne2022-12-121-0/+3
| | | | | | Task-number: QTBUG-104189 Change-Id: Ic2d27debd689757836478a55d3927ce9bbcd3849 Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* CMake: Add qt 'policy' supportFabian Kosmale2022-12-103-1/+69
| | | | | | | | | | | | | | | | | | | | | This mimics CMake's policy support. The policy state is stored in an internal __QT_INTERNAL_POLICY_<policy> variable; by using normal variables, we gain support for stacking for free. Policies can be explicitly en- or disable via qt6_policy; that command also has a GET mode to retrieve them again. Furthermore, one can now pass min and max version to qt6_standard_project_setup, to opt in to a certain set of defaults introduced in a given Qt version. We add support for policies in QtModuleHelpers, so that we can check for known policies while building Qt itself. No actual policies exist yet; but a follow up commit will introduce one for qt_add_qml_module. Change-Id: I57a0404c9193926dd499f94cc5f73e359355c0b3 Reviewed-by: Marc Mutz <marc.mutz@qt.io> Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* Adapt QDateTime to route QTimeSpec uses via QTimeZoneEdward Welbourne2022-12-091-0/+8
| | | | | | | | | | | | | | | | | | | | | | Free most APIs using QTimeZone from feature timezone and route all APIs taking a naked QTimeSpec via these, in preparation for their eventual deprecation. Since qtimezone.h includes qdatetime.h (and MSVC blocks our ability to remove the need for that), qdatetime.h's declarations can't use a default value for QTimeZone parameters; so add overloads taking no zone (or spec) to handle that. [ChangeLog][QtCore][QDateTime] All QDateTime APIs involving a Qt::TimeSpec can now be routed via QTimeZone's lightweight time description support, saving the need to have different code paths for different time specs. In the process, QDateTime gains a timeRepresentation() method to return a QTimeZone reporting the (possibly lightweight) time description it uses. (The older timeZone() method always returns a non-lightweight QTimeZone, whose timeSpec() is Qt::TimeZone.) Task-number: QTBUG-108199 Change-Id: I23e43401eb2dbe9b7b534ca6401389920dd96b3c Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Document QT_ANDROID_MULTI_ABI_FORWARD_VARS CMake variableAlexey Edelev2022-12-081-0/+81
| | | | | | | | | | Add documentation for the QT_ANDROID_MULTI_ABI_FORWARD_VARS CMake variable. Pick-to: 6.4 Task-number: QTBUG-107893 Change-Id: Ia8dfd14a89d043c4f967464646388f57c96f911a Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* CMake: Un-TP most of the deployment APIAlexandru Croitor2022-12-085-11/+0
| | | | | | | | | | | | | | | They are deemed good enough. qt_deploy_translations is left in TP because with the current signature, it's not clear yet how it's supposed to work for iOS and other non-desktop targets. [ChangeLog][CMake] The Core CMake deployment API is out of Technical Preview status. Task-number: QTBUG-108507 Change-Id: I384233c697b33644de3c9e1fb17d04f44ca16ea2 Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
* CMake: Un-TP QT_RESOURCE_ALIASAlexandru Croitor2022-12-081-1/+0
| | | | | | | | | | | It is deemed good enough. [ChangeLog][CMake] The Core CMake QT_RESOURCE_ALIAS property is out of Technical Preview status. Change-Id: I50128a8ea4e82b3d15ff272eb713bc0f6a8b167d Fixes: QTBUG-109077 Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
* Doc: Document Qt Serialization with use casesJaishree Vyas2022-12-081-0/+138
| | | | | | | | | | | Added some background about Serialization with the classes and used cases. Fixes: QTBUG-103951 Pick-to: 6.4 6.3 6.2 Change-Id: I3ff179b814fc5d424f2ac2ffaf3237b90ddd7e2b Reviewed-by: Vladimir Minenko <vladimir.minenko@qt.io> Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io> Reviewed-by: Kai Köhne <kai.koehne@qt.io>
* Doc: Add documentation for qCFatal()Kai Köhne2022-12-051-0/+14
| | | | | Change-Id: Iad9ea51285300eb06fdd7e68dd747702cb0a80e5 Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
* wasm: add native QByteArray conversion functionsMorten Sørvig2022-12-051-0/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add functions which converts to and from JavaScript data arrays: static QByteArray::fromUint8Array(emscripten::val array) emscripten::val QByteArray::toUint8Array() const with corresponding internal qstdweb API: static Uint8Array Uint8Array::copyFrom(const QByteArray &buffer) QByteArray Uint8Array::copyToQByteArray() const Both functions will make a copy of the data, i.e. there is no shared reference counting. They take and return Uint8Array typed array views, via emscripten::val JavaScript object references. Unlike other native conversion functions, these have the special property that the data referenced by the native Uint8Array exists outside the heap memory area. This means we can’t e.g. memcpy the data. However, the heap is itself a JavaScript ArrayBuffer, and we can create a Uint8Array view to the buffer owned by the QByteArray, and then use JavaScript API to copy. See the qstdweb::Uint8Array::copy() implementation. That also means that a fromRawUint8Array() variant (which does not copy) is not possible to implement, since we can’t create a pointer to the source data. The inverse toRawUint8Array() is implementable - it would return a Uint8Array view which references the heap’s ArrayBuffer. However, this may turn out to be ill-advised, since Emscripten will create a new ArrayBuffer if/when it resizes the heap. In any case this left for a future expansion. Change-Id: Icaf48fd17ea8686bf04cb523cc1eb581ce63ed34 Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io> Reviewed-by: Lorn Potter <lorn.potter@gmail.com>
* Docs: Document the QT_ANDROID_SDK_BUILD_TOOLS_REVISION CMake variableNicholas Bennett2022-12-051-0/+20
| | | | | | | | | | | When updating Qt for Android platform documentation, it was discovered that the CMake variable for setting a specific Android SDK Build Tools Revision was undocumented. Pick-to: 6.2 6.4 Change-Id: I5f1b4e9d10b9ce817f5529cf4897bd0423a84455 Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io> Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>
* Add \brief descriptions to CMake overviewsKai Köhne2022-12-033-0/+5
| | | | | | | | | Add brief descriptions of the pages that are shown in https://doc.qt.io/qt-6/overviews.html Pick-to: 6.4 Change-Id: I177e4ba82cd7b8e264122375bf9a595509918fdd Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
* Brush up the container documentationFriedemann Kleint2022-12-022-15/+14
| | | | | | | | | Make the code snippets consistent, update the comparison table and fix some sentences. Pick-to: 6.4 6.2 Change-Id: Ic8baaa56805392855736164efa03d065330309fa Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QBindable: Make ordinary Q_PROPERTYs bindablePatrick Stewart2022-11-301-0/+14
| | | | | | | | | | | Implements an adaptor from the notification signal of a Q_PROPERTY to QBindable. The Q_PROPERTY does not need to be BINDABLE, but can still be bound or used in a binding. [ChangeLog][Core][Q_PROPERTY] Q_PROPERTYs without BINDABLE can be wrapped in QBindable to make them usable in bindings Change-Id: Id0ca5444b93a371ba8720a38f3607925d393d98a Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* Use the browser compositor for drawing windows on WASMMikolaj Boc2022-11-261-1/+1
| | | | | | | | | | | | | | | | Make the browser compositor draw the window non-client area (using css + html). Get rid of OpenGL usage in non-OpenGL windows and use canvas 2d context instead to blit the texture (QImage). Also, as part of the change, remove the deprecated canvas element support in QScreen. Fixes: QTBUG-107116 Fixes: QTBUG-107219 Change-Id: I65f0d91831c806315685ca681ac0e416673f5cd5 Reviewed-by: Morten Johan Sørvig <morten.sorvig@qt.io> Reviewed-by: Aleksandr Reviakin <aleksandr.reviakin@qt.io> Reviewed-by: David Skoland <david.skoland@qt.io>
* Documentation: Fix information on how to iterate over listsFriedemann Kleint2022-11-241-18/+0
| | | | | | | | | | | | Remove the outdated code used for QStringList and point QStringList and QList to the containers page. Pick-to: 6.4 6.2 Task-number: QTBUG-108687 Change-Id: I6fae6410ca759f91da85832ddb9f24e8a0ce202b Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io> Reviewed-by: Marc Mutz <marc.mutz@qt.io>
* Documentation: Expand documentation on how to iterate Qt containersFriedemann Kleint2022-11-242-4/+48
| | | | | | | | | | Introduce a section on iteration and add range-based for and index. Pick-to: 6.4 6.2 Task-number: QTBUG-108687 Change-Id: Icb1ff55049361769f7c0b042d42f70148dd07c2e Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io> Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
* Documentation: Modernize the Qt container doc snippetsFriedemann Kleint2022-11-241-23/+15
| | | | | | | | | | | Use auto and initializer lists. Avoid repeated instantiations of end(). Pick-to: 6.4 6.2 Task-number: QTBUG-108687 Change-Id: I8482638cda63e21feaa7ca21370e7947dfb4b606 Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io> Reviewed-by: Marc Mutz <marc.mutz@qt.io>
* Modernize QMessageBox documentation and exampleTor Arne Vestbø2022-11-181-2/+2
| | | | | | Change-Id: Iebcdf53646f1a42c327414edf21ac93a7d1c0a56 Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* Doc: Normalize page namesKai Köhne2022-11-0227-69/+69
| | | | | | | | | | | | | | | qdoc does enforce lowercase file names for .html pages, and also replaces underscore with a dash. Make sure that the original \page name already is normalized, so that it's easier to search. This was done by find . -name "*.qdoc" -exec perl -p -i -E "s/\\\page (.*)/\\\page \L\1/ && s/_/-/g" {} ; Pick-to: 6.4 Change-Id: Ib50b85af8ffd985edf06856266eefdebf8b328a3 Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Luca Di Sera <luca.disera@qt.io> Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Long live QPermissions!Tor Arne Vestbø2022-11-013-1/+54
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Many features of today's devices and operating systems can have significant privacy, security, and performance implications if misused. It's therefore increasingly common for platforms to require explicit consent from the user before accessing these features. The Qt permission APIs allow the application to check or request permission for such features in a cross platform manner. The check is always synchronous, and can be used in both library and application code, from any thread. The request is asynchronous, and should be initiated from application code on the main thread. The result of the request can be delivered to lambdas, standalone functions, or regular member functions such as slots, with an optional context parameter to manage the lifetime of the request. Individual permissions are distinct types, not enum values, and can be added and extended at a later point. Task-number: QTBUG-90498 Done-with: Timur Pocheptsov <timur.pocheptsov@qt.io> Done-with: Volker Hilsheimer <volker.hilsheimer@qt.io> Done-with: Mårten Nordheim <marten.nordheim@qt.io> Change-Id: I821380bbe56bbc0178cb43e6cabbc99fdbd1235e Reviewed-by: Timur Pocheptsov <timur.pocheptsov@qt.io>
* QHash: tame HasQHashSingleArgOverload ODR violationsGiuseppe D'Angelo2022-11-011-3/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | qhashfunctions.h defines a catch-all 2-arguments qHash(T, seed) in order to support datatypes that implement a 1-argument overload of qHash (i.e. qHash(Type)). The catch-all calls the 1-argument overload and XORs the result with the seed. The catch-all is constrained on the existence of such a 1-argument overload. This is done in order to make the catch-all SFINAE-friendly; otherwise merely instantiating the catch-all would trigger a hard error. Such an error would make it impossible to build a type trait that detects if one can call qHash(T, size_t) for a given type T. The constraint itself is called HasQHashSingleArgOverload and lives in a private namespace. It has been observed that HasQHashSingleArgOverload misbehaves for some datatypes. For instance, HasQHashSingleArgOverload<int> is actually false, despite qHash(123) being perfectly callable. (The second argument of qHash(int, size_t) is defaulted, so the call *is* possible.) -- Why is HasQHashSingleArgOverload<int> false? This has to do with how HasQHashSingleArgOverload<T> is implemented: as a detection trait that checks if qHash(declval<T>()) is callable. The detection itself is not a problem. Consider this code: template <typename T> constexpr bool HasQHashSingleArgOverload = /* magic */; class MyClass {}; size_t qHash(MyClass); static_assert(HasQHashSingleArgOverload<MyClass>); // OK Here, the static_assert passes, even if qHash(MyClass) (and MyClass itself) were not defined at all when HasQHashSingleArgOverload was defined. This is nothing but 2-phase lookup at work ([temp.dep.res]): the detection inside HasQHashSingleArgOverload takes into account the qHash overloads available when HasQHashSingleArgOverload was declared, as well as any other overload declared before the "point of instantiation". This means that qHash(MyClass) will be visible and detected. Let's try something slightly different: template <typename T> constexpr bool HasQHashSingleArgOverload = /* magic */; size_t qHash(int); static_assert(HasQHashSingleArgOverload<int>); // ERROR This one *does not work*. How is it possible? The answer is that 2-phase name lookup combines the names found at definition time with the names _found at instantiation time using argument-dependent lookup only_. `int` is a fundamental type and does not participate in ADL. In the example, HasQHashSingleArgOverload has actually no qHash overloads to even consider, and therefore its detection fails. You can restore detection by moving the declaration of the qHash(int) overload *before* the definition of HasQHashSingleArgOverload, so it's captured at definition time: size_t qHash(int); template <typename T> constexpr bool HasQHashSingleArgOverload = /* magic */; static_assert(HasQHashSingleArgOverload<int>); // OK! This is why HasQHashSingleArgOverload<int> is currently returning `false`: because HasQHashSingleArgOverload is defined *before* all the qHash(fundamental_type) overloads in qhashfunctions.h. -- Now consider this variation of the above, where we keep the qHash(int) overload after the detector (so, it's not found), but also prepend an Evil class implicitly convertible from int: struct Evil { Evil(int); }; size_t qHash(Evil); template <typename T> constexpr bool HasQHashSingleArgOverload = /* magic */; size_t qHash(int); static_assert(HasQHashSingleArgOverload<int>); // OK Now the static_assert passes. HasQHashSingleArgOverload is still not considering qHash(int) (it's declared after), but it's considering qHash(Evil). Can you call *that* one with an int? Yes, after a conversion to Evil. This is extremely fragile and likely an ODR violation (if not ODR, then likely falls into [temp.dep.candidate/1]). -- Does this "really matter" for a type like `int`? The answer is no. If HasQHashSingleArgOverload<int> is true, then a call like qHash(42, 123uz); will have two overloads in its overloads set: 1) qHash(int, size_t) 2) qHash(T, size_t), i.e. the catch-all template. To be pedantic, qHash<int>(const int &, size_t), that is, the instantiation of the catch-all after template type deduction for T (= int) ([over.match.funcs.general/8]). Although it may look like this is ambiguous as both calls have perfect matches for the arguments, 1) is actually a better match than 2) because it is not a template specialization ([over.match.best/2.4]). In other words: qHash(int, size_t) is *always* called when the argument is `int`, no matter the value of HasQHashSingleArgOverload<int>. The catch-all template may be added or not to the overload set, but it's a worse match anyways. -- Now, let's consider this code: enum MyEnum { E1, E2, E3 }; qHash(E1, 42uz); This code compiles, although we do not define any qHash overload specifically for enumeration types (nor one is defined by MyEnum's author). Which qHash overload gets called? Again there are two possible overloads available: 1) qHash(int, size_t). E1 can be converted to `int` ([conv.prom/3]), and this overload selected. 2) qHash(T, size_t), which after instantiation, is qHash<MyEnum>(const MyEnum &, size_t). In this case, 2) is a better match than 1), because it does not require any conversion for the arguments. Is 2) a viable overload? Unfortunately the answer here is "it depends", because it's subject to what we've learned before: since the catch-all is constrained by the HasQHashSingleArgOverload trait, names introduced before the trait may exclude or include the overload. This code: #include <qhashfunctions.h> enum MyEnum { E1, E2, E3 }; qHash(E1, 42uz); static_assert(HasQHashSingleArgOverload<MyEnum>); // ERROR will fail the static_assert. This means that only qHash(int, size_t) is in the overload set. However, this code: struct Evil { Evil(int); }; size_t qHash(Evil); #include <qhashfunctions.h> enum MyEnum { E1, E2, E3 }; qHash(E1, 42uz); static_assert(HasQHashSingleArgOverload<MyEnum>); // OK will pass the static_assert. qHash(Evil) can be called with an object of type MyEnum after an user-defined conversion sequence ([over.best.ics.general], [over.ics.user]: a standard conversion sequence, made of a lvalue-to-rvalue conversion + a integral promotion, followed by a conversion by constructor [class.conv.ctor]). Therefore, HasQHashSingleArgOverload<MyEnum> is true here; the catch-all template is added to the overload set; and it's a best match for the qHash(E1, 42uz) call. -- Is this a problem? **Yes**, and a huge one: the catch-all template does not yield the same value as the qHash(int, size_t) overload. This means that calculating hash values (e.g. QHash, QSet) will have different results depending on include ordering! A translation unit TU1 may have #include <QSet> #include <Evil> QSet<MyEnum> calculateSet { /* ... */ } And another translation unit TU2 may have #include <Evil> #include <QSet> // different order void use() { QSet<MyEnum> set = calculateSet(); } And now the two TUs cannot exchange QHash/QSet objects as they would hash the contents differently. -- `Evil` actually exists in Qt. The bug report specifies QKeySequence, which has an implicit constructor from int, but one can concoct infinite other examples. -- Congratulations if you've read so far. ========================= === PROPOSED SOLUTION === ========================= 1) Move the HasQHashSingleArgOverload detection after declaring the overloads for all the fundamental types (which we already do anyways). This means that HasQHashSingleArgOverload<fundamental_type> will now be true. It also means that the catch-all becomes available for all fundamental types, but as discussed before, for all of them we have better matches anyways. 2) For unscoped enumeration types, this means however an ABI break: the catch-all template becomes always the best match. Code compiled before this change would call qHash(int, size_t), and code compiled after this change would call the catch-all qHash<Enum>(Enum, size_t); as discussed before, the two don't yield the same results, so mixing old code and new code will break. In order to restore the old behavior, add a qHash overload for enumeration types that forwards the implementation to the integer overloads (using qToUnderlying¹). (Here I'm considering the "old", correct behavior the one that one gets by simply including QHash/QSet, declaring an enumeration and calling qHash on it. In other words, without having Evil around before including QHash.) This avoids an ABI break for most enumeration types, for which one does not explicitly define a qHash overload. It however *introduces* an ABI break for enumeration types for which there is a single-argument qHash(E) overload. This is because - before this change, the catch-all template was called, and that in turn called qHash(E) and XOR'ed the result with the seed; - after this change, the newly introduced qHash overload for enumerations gets called. It's very likely that it would not give the same result as before. I don't have a solution for this, so we'll have to accept the ABI break. Note that if one defines a two-arguments overload for an enum type, then nothing changes there (the overload is still the best match). 3) Make plans to kill the catch-all template, for Qt 7.0 at the latest. We've asked users to provide a two-args qHash overload for a very long time, it's time to stop working around that. 4) Make plans to switch from overloading qHash to specializing std::hash (or equivalent). Specializations don't overload, and we'd get rid of all these troubles with implicit conversions. -- ¹ To nitpick, qToUnderlying may select a *different* overload than the one selected by an implicit conversion. That's because an unscoped enumeration without a fixed underlying type is allowed to have an underlying type U, and implicitly convert to V, with U and V being two different types (!). U is "an integral type that can represent all the enumerator values" ([dcl.enum/7]). V is selected in a specific list in a specific order ([conv.prom]/3). This means that in theory a compiler can take enum E { E1, E2 }, give it `unsigned long long` as underlying type, and still allow for a conversion to `int`. As far as I know, no compiler we use does something as crazy as that, but if it's a concern, it needs to be fixed. [ChangeLog][Deprecation Notice] Support for overloads of qHash with only one argument is going to be removed in Qt 7. Users are encouraged to upgrade to the two-arguments overload. Please refer to the QHash documentation for more information. [ChangeLog][Potentially Binary-Incompatible Changes] If an enumeration type for which a single-argument qHash overload has been declared is being used as a key type in QHash, QMultiHash or QSet, then objects of these types are no longer binary compatible with code compiled against an earlier version of Qt. It is very unlikely that such qHash overloads exist, because enumeration types work out of the box as keys Qt unordered associative containers; users do not need to define qHash overloads for their custom enumerations. Note that there is no binary incompatibity if a *two* arguments qHash overload has been declared instead. Fixes: QTBUG-108032 Fixes: QTBUG-107033 Pick-to: 6.2 6.4 Change-Id: I2ebffb2820c553e5fdc3a341019433793a58e3ab Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io> Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Doc: Fix typo in container documentationPaul Wicking2022-10-261-1/+1
| | | | | | | Pick-to: 6.4 Change-Id: Ia36cdff5554955e5193a10b9f0e4aab3c61e5f09 Reviewed-by: Axel Spoerl <axel.spoerl@qt.io> Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Make the `PREFIX` Parameter of the `qt_add_resources` OptionalAmir Masoud Abdol2022-10-251-1/+3
| | | | | | | | | | | | | | | | The `rcc_PREFIX` will be set to `/` if it is not passed to the function and it is not defined in `QT_RESOURCE_PREFIX`. I also removed an unnecessary check of the `rcc_PREFIX`. [ChangeLog][QtCore][CMake] The `PREFIX` parameter of the `qt_add_resources` is now optional. If not passed, and `QT_RESOURCE_PREFIX` is not defined, `/` will be used as the path prefix. Fixes: QTBUG-104938 Change-Id: I6524ab5dc54f035272e4c2e3154eb67591efb650 Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
* Layouts docs: pass parent widget in the ctorAhmad Samir2022-10-212-9/+6
| | | | | | | | | This is a follow up from commit 1e904ab342c1aaa; changing more documentation to pass a widget * in the ctor of a layout, rather than creating a parent-less layout then calling setLayout(). Change-Id: I4fc59c6cfa46ccd279a153acd67335a6daf22ff9 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* Long live Q_UNREACHABLE_RETURN()!Marc Mutz2022-10-151-0/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This is a combination of Q_UNREACHABLE() with a return statement. ATM, the return statement is unconditionally included. If we notice that some compilers warn about return after __builtin_unreachable(), then we can map Q_UNREACHABLE_RETURN(...) to Q_UNREACHABLE() without having to touch all the code that uses explicit Q_UNREACHABLE() + return. The fact that Boost has BOOST_UNREACHABLE_RETURN() indicates that there are compilers that complain about a lack of return after Q_UNREACHABLE (we know that MSVC, ICC, and GHS are among them), as well as compilers that complained about a return being present (Coverity). Take this opportunity to properly adapt to Coverity, by leaving out the return statement on this compiler. Apply the macro around the code base, using a clang-tidy transformer rule: const std::string unr = "unr", val = "val", ret = "ret"; auto makeUnreachableReturn = cat("Q_UNREACHABLE_RETURN(", ifBound(val, cat(node(val)), cat("")), ")"); auto ignoringSwitchCases = [](auto stmt) { return anyOf(stmt, switchCase(subStmt(stmt))); }; makeRule( stmt(ignoringSwitchCases(stmt(isExpandedFromMacro("Q_UNREACHABLE")).bind(unr)), nextStmt(returnStmt(optionally(hasReturnValue(expr().bind(val)))).bind(ret))), {changeTo(node(unr), cat(makeUnreachableReturn, ";")), // TODO: why is the ; lost w/o this? changeTo(node(ret), cat(""))}, cat("use ", makeUnreachableReturn)) ); where nextStmt() is copied from some upstream clang-tidy check's private implementation and subStmt() is a private matcher that gives access to SwitchCase's SubStmt. A.k.a. qt-use-unreachable-return. There were some false positives, suppressed them with NOLINTNEXTLINE. They're not really false positiives, it's just that Clang sees the world in one way and if conditonal compilation (#if) differs for other compilers, Clang doesn't know better. This is an artifact of matching two consecutive statements. I haven't figured out how to remove the empty line left by the deletion of the return statement, if it, indeed, was on a separate line, so post-processed the patch to remove all the lines matching ^\+ *$ from the diff: git commit -am meep git reset --hard HEAD^ git diff HEAD..HEAD@{1} | sed '/^\+ *$/d' | recountdiff - | patch -p1 [ChangeLog][QtCore][QtAssert] Added Q_UNREACHABLE_RETURN() macro. Change-Id: I9782939f16091c964f25b7826e1c0dbd13a71305 Reviewed-by: Marc Mutz <marc.mutz@qt.io> Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* CMake: Add filter options to qt_generate_deploy_app_scriptJoerg Bornemann2022-10-151-0/+12
| | | | | | | | | | | | Add the options PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES, and POST_EXCLUDE_FILES. These are forwarded to qt_deploy_runtime_dependencies. Change-Id: I003814bec7f797a0035e52b17fd0231f9ad7ff0d Reviewed-by: Paul Wicking <paul.wicking@qt.io> Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io> Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
* CMake: Deploy runtime dependencies outside of the Qt prefix tooJoerg Bornemann2022-10-152-0/+49
| | | | | | | | | | | | | | | | | | | | | | | | We restricted the runtime dependencies we deployed on Linux to libraries within the Qt installation prefix. This restriction was supposed to prevent the deployment of all kinds of system libraries, which is most likely not wanted. However, the user might link against non-system libraries, and those should be deployed. The same holds for QML backend libraries that exist outside the Qt installation prefix in the build directory of the project. Now, we restrict deployment to libraries that are not in default system library directories. This can be overridden with the new qt_deploy_runtime_dependencies option POST_EXCLUDE_REGEXES. We add the following options to qt_deploy_runtime_dependencies, which are then forwarded to file(GET_RUNTIME_DEPENDENCIES): PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, and POST_INCLUDE_FILES. Change-Id: I99a98fd91218abedda270609d0bafbb7f3e0feeb Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* QString/doc: correct the record on const char* optimizationsThiago Macieira2022-10-021-0/+3
| | | | | | | | | | | This portion of the documentation was there since the Qt 4.5 import of the repository and may have been correct at the time. They haven't been for some time and definitely aren't now. So be clear that even if there are overloads, some of them are bad ideas. Pick-to: 6.2 6.3 6.4 Change-Id: I810d70e579eb4e2c8e45fffd1719adefb6f9f3bf Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
* QMetaType: Support custom unary converters with optional<To> return typeArno Rehn2022-09-271-0/+8
| | | | | | | | | | | | | | | To indicate success of a conversion, the public API has previously only supported registering member functions of the form To (From::*)(bool *). When adding custom converters for types that cannot be modified, this is usually not a possibility. As an alternative, this patch adds support for std::optional in the UnaryFunction overload of QMetaType::registerConverter. If the returned optional has no value, the conversion is considered failed. Task-number: QTBUG-92902 Change-Id: Ibac52d2cb9b5a2457081b4bebb0def1f03e3c55d Reviewed-by: Thiago Macieira <thiago.macieira@intel.com> Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* CMake: Add finalization to plugins created with qt_add_pluginJoerg Bornemann2022-09-232-0/+15
| | | | | | | | | | | | Add the MANUAL_FINALIZATION option to qt_add_plugin and run qt_finalize_target like we do for qt_add_executable and qt_add_library. Currently, the only user-visible effect is that resource files are put into a FOLDER and not underneath a XXX_other_files target. Change-Id: I430d87b5357f6d2ed7fe32198a73eb919f393dd8 Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* Doc: Update the animation framework overviewVenugopal Shivashankar2022-09-202-205/+227
| | | | | | | | | | | - Clarify how the object ownership works - Language clean up - Update the snippets Pick-to: 6.4 6.3 6.2 Task-number: QTBUG-106071 Change-Id: I7caf42a150ef82dee920df4d03db6fd988796bd4 Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
* CMake: Add NO_TRANSLATIONS option to deployment functionsJoerg Bornemann2022-09-152-0/+12
| | | | | | | | | | | | Add the NO_TRANSLATIONS option to qt_deploy_runtime_dependencies and qt_generate_deploy_app_script. On Windows and Linux, this option prevents the deployment of Qt translations. [ChangeLog][CMake] Added the NO_TRANSLATIONS option to qt_deploy_runtime_dependencies and qt_generate_deploy_app_script. Change-Id: I9d8435e262e2ff6c7242760ddb189473af850476 Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* CMake: Introduce qt_deploy_translationsJoerg Bornemann2022-09-152-5/+114
| | | | | | | | | | | | | | Add the command qt_deploy_translations to the CMake deployment API. This can be used to deploy a set of Qt translations. This command is supposed to be called by the generic deployment tool in a future commit. [ChangeLog][CMake] Added qt_deploy_translations for deploying Qt translation catalogs in user projects. Change-Id: I4492a5042970cf89b2be2ed0c34521c7af904771 Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* CMake: Add Linux support to qt_deploy_runtime_dependenciesJoerg Bornemann2022-09-151-2/+6
| | | | | | | | | | | | | | | | | | | | | | Before this change, qt_deploy_runtime_dependencies supported Windows and macOS only. We add a generic deployment method implemented in cmake-language with file(GET_RUNTIME_DEPENDENCIES). This deployment method is now enabled for shared builds on Linux. The file(GRD) command requires that the EXECUTABLE argument points to the executable in the build directory. Only libraries in Qt's installation directory are considered for deployment. This includes Qt's own libraries and also things like libicu*.so we're shipping with the installer. Unlike macdeployqt and windeployqt, the generic qt_deploy_runtime_dependencies does not yet support deploying translations. We will catch up on this in a later commit. Change-Id: Iea23abcdba774d4c1885c8d2c243eb3e48fb7fae Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* CMake: Clarify qt_deploy_runtime_dependencies' EXECUTABLE argumentJoerg Bornemann2022-09-121-5/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | In a subsequent commit we will add Linux support for qt_deploy_runtime_dependencies based on file(GET_RUNTIME_DEPENDENCIES). The file(GRD) command expects that we pass the not-yet-installed executable to it, because the command reads the RUNPATH/RPATH from the executable and resolves libraries against these paths. This resolution is likely going to fail if file(GRD) is run on an installed executable, because the RPATH was modified to be relocatable in the installation phase. This patch adds a recommendation to use the build directory's executable for qt_deploy_runtime_dependencies on non-macOS platforms. Also, the Windows code path of qt_deploy_runtime_dependencies is adjusted to support both, the .exe in the build dir and the .exe in the installation prefix. For consistency, qt_generate_deploy_app_script calls qt_deploy_runtime_dependencies with EXECUTABLE pointing to the build directory's executable. [ChangeLog][CMake] On non-macOS platforms, qt_deploy_runtime_dependencies' EXECUTABLE argument now expects the executable in the build directory instead of the installation directory. Change-Id: Id76b52cc5a0f285586679d7ae600a8c7996429c1 Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
* CMake: Introduce qt_generate_deploy_scriptJoerg Bornemann2022-09-115-11/+105
| | | | | | | | | | | | | | | | | | Should the deployment script that qt_generate_deploy_app_script not be sufficient, the new function qt_generate_deploy_script can be used to generate a custom deployment script. Before, one had to add quite some boilerplate code to generate a custom deployment script. The qt_generate_deploy_app_script function now uses qt_generate_deploy_script internally. The TARGET option of qt_generate_deploy_script is currently only used for controlling the base name of the generated deployment script. We will do more with the target in a subsequent commit. Fixes: QTBUG-105731 Change-Id: I85bfc50dac1f0b0b1aae0f657f803e9e30f53616 Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
generated by cgit v1.2.1 (git 2.18.0) at 2023-01-30 15:52:54 +0000