summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc/snippets/code
Commit message (Collapse)AuthorAgeFilesLines
...
* 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>
* 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>
* 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>
* 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>
* Doc: Update the animation framework overviewVenugopal Shivashankar2022-09-201-5/+89
| | | | | | | | | | | - 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>
* QMetaObject/Doc: document the variadic invoke{,Method} and newInstanceThiago Macieira2022-09-011-0/+33
| | | | | Change-Id: Ic6547f8247454b47baa8fffd170dc646d4f73152 Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
* QMetaType/Doc: update some wording about type registrationThiago Macieira2022-08-291-5/+5
| | | | | | | | | | | | | | | Type registration isn't necessary any more, unless you're trying to look up a name back to ID or QMetaType object. It hasn't been since 6.0. Drive-by update the example not to use deprecated API. Drive-by remove the paragraph about requirements that aren't accurate any more. Pick-to: 6.4 Task-number: QTBUG-104858 Change-Id: Ic6547f8247454b47baa8fffd170eecb66719fa65 Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* Doc: Remove qmake-only reference in Q_IMPORT_PLUGIN descriptionKai Köhne2022-08-241-4/+0
| | | | | | | | | | The Static Plugins page describes handling of qmake and CMake already in greater detail. No need to replicate it here. Pick-to: 6.4 Task-number: QTBUG-88044 Change-Id: I2cae85c0b0d20585b563bab9e263121181adeb8c Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
* [docs] Fix return value of QStringIterator::next()Marc Mutz2022-08-111-1/+1
| | | | | | | | | | It's char32_t these days, not uint. Task-number: QTBUG-103531 Pick-to: 6.4 6.3 6.2 Change-Id: Iaa03f97d0d1266a6763eb858edb45ae0f2a4729d Reviewed-by: Sona Kurazyan <sona.kurazyan@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* Move q{,Utf8, Utf16}Printable to qstring.hSona Kurazyan2022-08-042-10/+8
| | | | | | | Task-number: QTBUG-99313 Change-Id: I76ef84e4c90ab04a3e04c165ba46800e27ea6122 Reviewed-by: Edward Welbourne <edward.welbourne@qt.io> Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
* QAbstractNativeEventFilter: Fix the Mac example class nameLaszlo Papp2022-08-041-1/+1
| | | | | | Change-Id: I838350883fa6bd8c80f87fba18f006afd905ed61 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com> Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>
* QAbstractNativeEventFilter: Add a Windows exampleLaszlo Papp2022-08-021-0/+20
| | | | | Change-Id: Ic378174e7f192abc27524cbcd925705c8bb46502 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Remove outdated docs for qOverload()Sona Kurazyan2022-08-011-5/+0
| | | | | Change-Id: Ie641b1f7100e7053e1fe0299a0b2b0bd708326af Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* QMap: remove more docs referring to multiple values for the same keyGiuseppe D'Angelo2022-05-291-16/+0
| | | | | | | | Such semantics have been dropped from Qt 6. Change-Id: I12f3478833afafa34f9075faf9ed030d06cd86f9 Pick-to: 6.2 6.3 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Use SPDX license identifiersLucie Gérard2022-05-16112-5490/+226
| | | | | | | | | | | | | Replace the current license disclaimer in files by a SPDX-License-Identifier. Files that have to be modified by hand are modified. License files are organized under LICENSES directory. Task-number: QTBUG-67283 Change-Id: Id880c92784c40f3bbde861c0d93f58151c18b9f1 Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Lars Knoll <lars.knoll@qt.io> Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
* Add support for unwrapping QFuture<QFuture<T>>Sona Kurazyan2022-04-211-0/+34
| | | | | | | | | | | | | | | | Added QFuture::unwrap() for unwrapping the future nested inside QFuture<QFuture<T>>. QTBUG-86725 suggests doing the unwrapping automatically inside .then(), but this will change the return type of .then() that used to return QFuture<QFuture<T>> and might cause SC breaks. Apart from that, QFuture::unwrap() might be helpful in general, for asynchronous computations that return a nested QFuture. [ChangeLog][QtCore][QFuture] Added QFuture::unwrap() for unwrapping the future nested inside QFuture<QFuture<T>>. Task-number: QTBUG-86725 Change-Id: I8886743aca261dca46f62d9dfcaead4a141d3dc4 Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* QDate: add conversions for std::chrono calendaring classesGiuseppe D'Angelo2022-04-131-0/+20
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | std::chrono::year_month_day and related classes offer very convenient to specify dates. This patch adds implicit constructors to QDate to support this convenience, e.g.: // YYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY formats: QDate d1 = 1985y / December / 8; QDate d2 = 8d / December / 1985; QDate d3 = December / 8d / 1985; // Indexed weekday: QDate d4 = 2000y / January / Monday[0]; QDate d5 = 2000y / January / Monday[last]; and so on. These are all implemented using the conversion from the std calendaring classes to sys_days. Conversions between sys_days and QDate are also added, since they're basically "for free". I don't expect "ordinary" users to stumble upon it, but it's worthy mentioning that std::chrono::year *does* have a year zero (hence, year_month_day in year 0 or below are offset by one with the corresponding QDate). I've left a note in the documentation. [ChangeLog][QtCore][QDate] QDate (and therefore QDateTime) is now constructible using the year/month/day/week classes available in the std::chrono library. Moreover, it now features conversions from and to std::chrono::sys_days. Change-Id: I2a4f56423ac7d1469541cbb6a278a65b48878b4a Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Doc: Document QT_NO_[SIGNALS_SLOTS_]KEYWORDS definesJoerg Bornemann2022-03-291-0/+5
| | | | | | | Pick-to: 6.2 6.3 Fixes: QTBUG-70564 Change-Id: I8ed1a30567dabdcb95cdfce009f1d9e0645d3226 Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* QtCore: replace QLatin1String/QLatin1Char with _L1/u'' where applicableSona Kurazyan2022-03-253-16/+22
| | | | | | | | | | | As a drive-by, did also minor refactorings/improvements. Task-number: QTBUG-98434 Change-Id: I81964176ae2f07ea63674c96f47f9c6aa046854f Reviewed-by: Edward Welbourne <edward.welbourne@qt.io> Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Thiago Macieira <thiago.macieira@intel.com> Reviewed-by: Anton Kudryavtsev <antkudr@mail.ru>
* Add QByteArray::percentDecoded() as an instance methodEdward Welbourne2022-03-181-2/+7
| | | | | | | | | | | | | Percent-decoding was previously only present as a static method taking a QBA parameter; it might as well be an instance method of that parameter. Change most QBA tests to use it rather the static method. [ChangeLog][QtCore][QByteArray] percentDecoded() is now available as an instance method of the byte array to be decoded, equivalent to the static QByteArray::fromPercentEncoding(). Change-Id: I982101c44bdac5cc4041e85598d52ac101d38fa1 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Associative containers: add a way to obtain a key/value rangeGiuseppe D'Angelo2022-03-043-0/+52
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Our associative containers' iterator's value_type isn't a destructurable type (yielding key/value). This means that something like for (auto [k, v] : map) doesn't even compile -- one can only "directly" iterate on the values. For quite some time we've had QKeyValueIterator to allow key/value iteration, but then one had to resort to a "traditional" for loop: for (auto i = map.keyValueBegin(), e = keyValueEnd(); i!=e; ++i) This can be easily packaged in an adaptor class, which is what this commmit does, thereby offering a C++17-compatible way to obtain key/value iteration over associative containers. Something possibly peculiar is the fact that the range so obtained is a range of pairs of references -- not a range of references to pairs. But that's easily explained by the fact that we have no pairs to build references to; hence, for (auto &[k, v] : map.asKeyValueRange()) doesn't compile (lvalue reference doesn't bind to prvalue pair). Instead, both of these compile: for (auto [k, v] : map.asKeyValueRange()) for (auto &&[k, v] : map.asKeyValueRange()) and in *both* cases one gets references to the keys/values in the map. If the map is non-const, the reference to the value is mutable. Last but not least, implement pinning for rvalue containers. [ChangeLog][QtCore][QMap] Added asKeyValueRange(). [ChangeLog][QtCore][QMultiMap] Added asKeyValueRange(). [ChangeLog][QtCore][QHash] Added asKeyValueRange(). [ChangeLog][QtCore][QMultiHash] Added asKeyValueRange(). Task-number: QTBUG-4615 Change-Id: Ic8506bff38b2f753494b21ab76f52e05c06ffc8b Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Doc: Make QListIterator snippets more robustKai Köhne2022-01-176-18/+22
| | | | | | | | | | | qDebug() << i.next(); can become a NOOP if the code is compiled with QT_NO_DEBUG_OUTPUT. Pick-to: 5.15 6.2 6.3 Fixes: QTBUG-97535 Change-Id: I9085b40ac9b4de2bb06f16e03fd5100902b08d4f Reviewed-by: Marc Mutz <marc.mutz@qt.io>
* Doc: Fix snippet to match actual QFileInfo behaviorKai Köhne2022-01-131-1/+1
| | | | | | | | | | The documentation was already updated in abfac029ceaf6c3199694a50, but the snippet still incorrectly suggested QFileInfo::size would report the actual size of an .lnk file on Windows. Pick-to: 5.15 6.2 6.3 Change-Id: I03b96b2efcb713fbc4dd30fc526e1209806bf5cf Reviewed-by: Oliver Wolff <oliver.wolff@qt.io>
* Doc: Replace "C:\Documents and Settings" pathsKai Köhne2022-01-122-4/+4
| | | | | | | | | | "C:\Documents and Settings" isn't a real path anymore since Windows Vista. Replace it by C:\Users, or - in the snippet for QDesktopServices that is for demoing a path with space - with C:\Program Files. Pick-to: 6.2 6.3 5.15 Change-Id: I1bef97b6482180a6467fffcd1d62d6c168bcb389 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Repair parameter typeChunLin Wang2021-12-033-3/+3
| | | | | | | | | Fix the parameter types corresponding to the sample code and subclasses Fixes: QTBUG-98578 Pick-to: 6.2 Change-Id: I06e342ae1210ed53c5deec3e2711457cf2ac5b15 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Add support for combining multiple QFuturesSona Kurazyan2021-11-201-0/+87
| | | | | | | | | | | [ChangeLog][QtCore] Added QtFuture::whenAll() and QtFuture::whenAny() functions, returning a QFuture that becomes ready when all or any of the supplied futures complete. Task-number: QTBUG-86714 Change-Id: I2bb7dbb4cdc4f79a7a4fd494142df6a0f93a2b39 Reviewed-by: Edward Welbourne <edward.welbourne@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* Add missing QT_TRID_N_NOOP definitionLucie Gérard2021-11-181-0/+14
| | | | | | | | | | | | | Amends c74bd2b93, properly following up on qttools/bc47b5190. [ChangeLog][QtCore] Added missing QT_TRID_N_NOOP() macro. Lupdate actually recognizes it since Qt 5.12. Fixes: QTBUG-98277 Fixes: QTBUG-3945 Change-Id: I0ea15ceb49b2ead5c8bb40d2a55a0ae8577e8850 Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de> Reviewed-by: Kai Koehne <kai.koehne@qt.io>
* QFuture: extend the docs to explain how to cancel continuation chainSona Kurazyan2021-11-151-0/+17
| | | | | | | Task-number: QTBUG-97582 Change-Id: Ib31d0dfb7a74bb88802a21c5875edd789e412529 Reviewed-by: Edward Welbourne <edward.welbourne@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QObjectComputedProperty docs: move example to snippetIvan Solovev2021-10-261-0/+37
| | | | | | | | | | | This patch amends 89a4c8d40d2ee1b8794dd7fcf80d226c5c87ba6c. It moves the code sample into a separate snippet file, which allows us to use Q_OBJECT macro in it without complaints from moc. Task-number: QTBUG-97656 Pick-to: 6.2 Change-Id: I368d8dd8c00dbbebd8a6bf3788be796c8ca4bce8 Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* QPoint: Don't claim that QPoint[F]::dotProduct() produces length squaredIevgenii Meshcheriakov2021-10-121-2/+2
| | | | | | | | | | | | | The documentation snippets name the result of dotProduct() "lengthSquared", but it is just a coincidence, not the property of dot product of two different points. Just name the result `dotProduct` without claiming any properties. Also fix the type of the result in the QPointF case. Fixes: QTBUG-94979 Change-Id: I4c337dd8335953489eac86c07a219c0a2d232369 Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* corelib: Fix typos in source code commentsJonas Kvinge2021-10-121-1/+1
| | | | | | Pick-to: 6.2 Change-Id: Ic78afb67143112468c6f84677ac88f27a74b53aa Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Improve version-related docs in qglobal.cppEdward Welbourne2021-09-211-2/+2
| | | | | | | | | | Give a more pragmatic illustration for QT_DEPRECATED_BEFORE. Make various minor tweaks to wording, use slightly less antique versions in examples. Make usage of "runtime" standard in qglobal.cpp, at least, since "run-time" seems to be less used generally. Change-Id: I1db4950d0d0e97903b1586d98ecba75576493b1c Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Encourage use of QT_VERSION_CHECK()Edward Welbourne2021-09-201-2/+2
| | | | | | | | | | | | Document that QT_VERSION should normally be compared against it, rather than raw hex, and mildly update the example versions used in docs. (Left the snippets testing old version, since the code in which the #if-ery is used might actually make sense for those versions.) Improve related documentation in the process. Change-Id: Id3e97f41bfb0f81a117cf7b3a3ccd5f244e2a99a Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Teach QByteArrayView how to parse numbersEdward Welbourne2021-08-301-1/+22
| | | | | | | | | | | | Now that we don't need '\0'-termination on the data, this is possible. Moved QByteArray's tests to tst_QByteArrayApiSymmetry and added some more test-cases. [ChangeLog][QtCore][QByteArrayView] Added numeric parsing methods. Change-Id: Ic0df91ecfe5dbf6f008d344dd0464d7927f32273 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* QLocale: improve documentation snippetIvan Solovev2021-08-261-9/+11
| | | | | | | | | | | | QString::toDouble() now always uses C locale, so the previous code snippet does not make much sense, as the results do not depend on the selected default locale. The updated snippet uses the default locale, which allows to show the difference between locales. Pick-to: 6.2 Change-Id: I76a00429fa5b75cf109cf45bc25280a7fd427e0f Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Doc: Replace the example for QFileInfo::setFileLuca Di Sera2021-08-252-10/+20
| | | | | | | | | | | | | | | | The example in the documentation of `QFileInfo::setFile` made no use of `setFile` and only showed a use of `QDir::setCurrent`. The example was replaced with a new example showing how `setFile` changes the file that the information are retrieved from. The old example was moved under the documentation for `QDir::setCurrent` as it shows its working. Fixes: QTBUG-87128 Pick-to: 6.2 6.1 5.15 Change-Id: I8227876cfcb4d582040bda9b4b7f3f7debea1e07 Reviewed-by: Paul Wicking <paul.wicking@qt.io>
* QRegularExpressionMatch: add a way to know if a capturing group capturedGiuseppe D'Angelo2021-08-251-0/+12
| | | | | | | | | | | | | | | | | | | | | | | Relying on the fact that a given capturing group captured a null string doesn't allow users to distinguish whether a capturing group did not capture anything, or captured a null substring (say, from a null subject string). Perl allows for the distinction: the entries in the @- and @+ arrays are set to values in case there is a capture, but they're undef otherwise. PCRE2 gives us the information already in the results "ovector", but it was simply not exposed to QREM users. So, expose it. [ChangeLog][QtCore][QRegularExpressionMatch] Added the hasCaptured() family of functions to know if a given capturing group has captured something. Change-Id: Ic1320933d4554e2e313c0a680be1b1b9dd95af0b Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org> Reviewed-by: Thiago Macieira <thiago.macieira@intel.com> Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io> Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Improve docs for QFuture continuationsSona Kurazyan2021-08-101-6/+6
| | | | | | | | | | | Replace phrases like "future has been running", "parent" with more precise descriptions. Pick-to: 6.1 6.2 Fixes: QTBUG-95273 Change-Id: Ibd5a464007d41cc437da49ba250b9ea0a46078c6 Reviewed-by: Andrei Golubev <andrei.golubev@qt.io> Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* QObject: optimize the common case of findChildren(QString())Marc Mutz2021-07-131-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Outside tests, all in-tree callers of QObject::findChildren() pass no name to match, and in my experience that is also true for the vast majority of out-of-tree users. Avoid the temporary QString creation in the caller and the repeated QString::isNull() checks in the implementation by overloading findChildren() without a name argument and checking for name.isNull() only once, forking off into separate helper functions. Adjust in-tree callers that used an explicit `QString()` argument in order to pass options, which goes to show that `name` should never have been the first argument of findChilden() in the first place, even though I appreciate the symmetry with findChild() (the use-cases of which, however, are radically different). Change a `findChildren().size() == 0` call found while scanning for findChildren() calls to `!findChild()` as a drive-by. Modernize loops in the various qt_qFindChild{,ren}_helper() overloads to match how the new code looks. [ChangeLog][QtCore][QObject] Added findChildren() overload taking no name (thus optimizing this common case). Change-Id: Ifc56e5438023d079b40c67f11ae274a3e128ad5e Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* Fix QStringEncoder code exampleNicolas Fella2021-07-061-1/+1
| | | | | | | | Make sure the right variable is used Pick-to: 6.2 Change-Id: Iec6d8392b320b704423ecbd4434270883fa9fd96 Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
* Doc: Use https for links to unicode.orgPaul Wicking2021-06-251-1/+1
| | | | | | | | | | * Change all outbound links in user-facing documentation. * Reflow lines that exceed 100 cols as mandated by clang-format. * Add unicode.org as a global \externalsite. Pick-to: 6.2 6.1 5.15 Change-Id: I2ba1e434aa913e678406d62c2801f1a8b2d9e4f4 Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* Doc: Fix snippet for QRandomGenerator64 docsPaul Wicking2021-06-141-1/+1
| | | | | | | Pick-to: 6.2 6.1 5.15 Fixes: QTBUG-94347 Change-Id: Iaf007534214cffc83858833e80dad447df9b297a Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
* Doc: Fix QVariant documentationKai Köhne2021-06-091-9/+5
| | | | | | | | | | Update documentation to not reference API that is obsolete in Qt 6. Also fix documentation for changed behavior (isNull()), and fix snippets. Pick-to: 6.1 6.2 Change-Id: I526efeff63d907bbadd5e8a539ccf237cb992125 Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* Make QLocale documentation more honestEdward Welbourne2021-04-151-4/+0
| | | | | | | | | | | | | | Documented the fall-back process by which QLocale selects an actual locale based on what it is asked for. The prior documentation was wrong. In the process, removed some out-of-date claims about QString's toInt() and toDouble() caring about the default locale; and caught a few more cases (in \internal docs) of country -> territory. Fixes: QTBUG-90962 Change-Id: I5e7cfa66443c9335a71fb2048c3f2ebf7af64573 Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
* Add example to QObjectBindableProperty change handler docsAndreas Buhr2021-03-251-0/+41
| | | | | | | | | QObjectBindableProperty has a callback, which is called whenever the value changes. This patch adds an example showing this. Task-number: QTBUG-90511 Change-Id: I56c0bce15af8121159630b5c0922c287c15b7618 Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
* The conditional statement is missing parenthesesZhang Yong2021-03-111-1/+1
| | | | | | | Add a ')' to the judgment statement. Change-Id: Iadfdfb7643bc5224cb3029a2abb42c3c14982eef Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
* QtGlobal docs: code tidiesZhang Yong2021-03-101-4/+2
| | | | | | | Reformat a couple of examples correctly. Change-Id: I2f0897267b4e3c4d7d2925f2d20cc45687278b0b Reviewed-by: Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
* Improve docs for QFuture::then() with contextSona Kurazyan2021-02-251-0/+11
| | | | | | | | | | | | | Be more precise about attaching a continuation with the default (QtFuture::Launch::Sync) launch policy after a continuation with context. Pick-to: 6.1 Change-Id: I5b80063df2443e5742033864ba012bf34ed4cdf7 Reviewed-by: Ivan Solovev <ivan.solovev@qt.io> Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io> Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io> Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
* Revert "Remove the qmake project files" for snippetsNico Vertriest2021-02-122-0/+9
| | | | | | | | | | | This reverts a limited part of commit ad2da2d27a590333fc89a56fc58700a09c3017b3 that deleted .pro files for snippets compilation. Some .pro files which contain snippets used in the documentation itself should be restored. Task-number: QTBUG-90483 Change-Id: I1b03833c8ff17b5fca43a5b6c5417e8545b1711b Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
* QBindable: add initial documentationFabian Kosmale2021-01-271-0/+12
| | | | | | Change-Id: I43681093c8819289037c76bd9c05b88a6da8311b Reviewed-by: Andrei Golubev <andrei.golubev@qt.io> Reviewed-by: Lars Knoll <lars.knoll@qt.io>
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-25 16:43:33 +0000