qt 6.5.1 original

doc/global/includes/cli-build-cmake.qdocinc

@@ -0,0 +1,42 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [cli-build-cmake]
+
+    \section1 Building and Running from the Command Line
+
+    To build an example application from the command line, create a build
+    directory for it. Switch to the build directory and run \c qt-cmake to
+    configure your project for building. If the project is configured
+    successfully, the generated files enable you to build the project.
+
+    \badcode
+    md <build_directory>
+    cd <build_directory>
+    <qt_installation_directory>\bin\qt-cmake -GNinja <source_directory>
+    <generator>
+    \endcode
+
+    The commands create an executable in the build directory. The \c CMake
+    tool reads the project file and produces instructions for how to build
+    the application. The generator then uses the instructions to produce
+    the executable binary.
+
+    For example, to build the Notepad example on Windows, when using Ninja
+    as the generator, enter the following commands:
+
+    \badcode \QtVersion
+    md notepad-build
+    cd notepad-build
+    C:\Qt\\1\msvc2019_64\bin\qt-cmake -GNinja C:\Examples\notepad
+    ninja
+    \endcode
+
+    If you do not use Ninja as the generator, use the generator-independent
+    CMake command to build the application instead of \c ninja:
+
+    \badcode
+    cmake --build
+    \endcode
+
+//! [cli-build-cmake]

doc/global/includes/corelib/port-from-qregexp.qdocinc

@@ -0,0 +1,175 @@
+// Copyright (C) 2022 Giuseppe D'Angelo <dangelog@gmail.com>.
+// Copyright (C) 2022 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [porting-to-qregularexpression]
+
+    The QRegularExpression class introduced in Qt 5 implements Perl-compatible
+    regular expressions and is a big improvement upon QRegExp in terms of APIs
+    offered, supported pattern syntax, and speed of execution. The biggest
+    difference is that QRegularExpression simply holds a regular expression,
+    and it's \e{not} modified when a match is requested. Instead, a
+    QRegularExpressionMatch object is returned, to check the result of a match
+    and extract the captured substring. The same applies to global matching and
+    QRegularExpressionMatchIterator.
+
+    Other differences are outlined below.
+
+    \note QRegularExpression does not support all the features available in
+    Perl-compatible regular expressions. The most notable one is the fact that
+    duplicated names for capturing groups are not supported, and using them can
+    lead to undefined behavior. This may change in a future version of Qt.
+
+    \section3 Different pattern syntax
+
+    Porting a regular expression from QRegExp to QRegularExpression may require
+    changes to the pattern itself.
+
+    In specific scenarios, QRegExp was too lenient and accepted patterns that
+    are simply invalid when using QRegularExpression. These are easy to detect,
+    because the QRegularExpression objects built with these patterns are not
+    valid (see QRegularExpression::isValid()).
+
+    In other cases, a pattern ported from QRegExp to QRegularExpression may
+    silently change semantics. Therefore, it is necessary to review the
+    patterns used. The most notable cases of silent incompatibility are:
+
+    \list
+
+    \li Curly braces are needed to use a hexadecimal escape like \c{\xHHHH}
+        with more than 2 digits. A pattern like \c{\x2022} needs to be ported
+        to \c{\x{2022}}, or it will match a space (\c{0x20}) followed by the
+        string \c{"22"}. In general, it is highly recommended to always use
+        curly braces with the \c{\x} escape, no matter the number of digits
+        specified.
+
+    \li A 0-to-n quantification like \c{{,n}} needs to be ported to \c{{0,n}}
+        to preserve semantics. Otherwise, a pattern such as \c{\d{,3}} would
+        match a digit followed by the exact string \c{"{,3}"}.
+
+    \li QRegExp by default does Unicode-aware matching, while
+        QRegularExpression requires a separate option; see below for more
+        details.
+
+    \li c{.} in QRegExp does by default match all characters, including the
+        newline character. QRegularExpression excludes the newline character
+        by default. To include the newline character, set the
+        QRegularExpression::DotMatchesEverythingOption pattern option.
+
+    \endlist
+
+    For an overview of the regular expression syntax supported by
+    QRegularExpression, please refer to the
+    \l{https://pcre.org/original/doc/html/pcrepattern.html}{pcrepattern(3)}
+    man page, describing the pattern syntax supported by PCRE (the reference
+    implementation of Perl-compatible regular expressions).
+
+    \section3 Porting from QRegExp::exactMatch()
+
+    QRegExp::exactMatch() served two purposes: it exactly matched a regular
+    expression against a subject string, and it implemented partial matching.
+
+    \section4 Porting from QRegExp's Exact Matching
+
+    Exact matching indicates whether the regular expression matches the entire
+    subject string. For example, the classes yield on the subject string \c{"abc123"}:
+
+    \table
+    \header \li                  \li QRegExp::exactMatch() \li QRegularExpressionMatch::hasMatch()
+    \row    \li \c{"\\d+"}       \li \b false              \li \b true
+    \row    \li \c{"[a-z]+\\d+"} \li \b true               \li \b true
+    \endtable
+
+    Exact matching is not reflected in QRegularExpression. If you want
+    to be sure that the subject string matches the regular expression
+    exactly, you can wrap the pattern using the QRegularExpression::anchoredPattern()
+    function:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 0
+
+    \section4 Porting from QRegExp's Partial Matching
+
+    When using QRegExp::exactMatch(), if an exact match was not found, one
+    could still find out how much of the subject string was matched by the
+    regular expression by calling QRegExp::matchedLength(). If the returned length
+    was equal to the subject string's length, then one could conclude that a partial
+    match was found.
+
+    QRegularExpression supports partial matching explicitly by means of the
+    appropriate QRegularExpression::MatchType.
+
+    \section3 Global matching
+
+    Due to limitations of the QRegExp API, it was impossible to implement global
+    matching correctly (that is, like Perl does). In particular, patterns that
+    can match 0 characters (like \c{"a*"}) are problematic.
+
+    QRegularExpression::globalMatch() implements Perl global match correctly, and
+    the returned iterator can be used to examine each result.
+
+    For example, if you have code like:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 1
+
+    You can rewrite it as:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 2
+
+    \section3 Unicode properties support
+
+    When using QRegExp, character classes such as \c{\w}, \c{\d}, etc. match
+    characters with the corresponding Unicode property: for instance, \c{\d}
+    matches any character with the Unicode \c{Nd} (decimal digit) property.
+
+    Those character classes only match ASCII characters by default when using
+    QRegularExpression: for instance, \c{\d} matches exactly a character in the
+    \c{0-9} ASCII range. It is possible to change this behavior by using the
+    QRegularExpression::UseUnicodePropertiesOption pattern option.
+
+    \section3 Wildcard matching
+
+    There is no direct way to do wildcard matching in QRegularExpression.
+    However, the QRegularExpression::wildcardToRegularExpression() method
+    is provided to translate glob patterns into a Perl-compatible regular
+    expression that can be used for that purpose.
+
+    For example, if you have code like:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 3
+
+    You can rewrite it as:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 4
+
+    Please note though that some shell-like wildcard patterns might not be
+    translated to what you expect. The following example code will silently
+    break if simply converted using the above-mentioned function:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 5
+
+    This is because, by default, the regular expression returned by
+    QRegularExpression::wildcardToRegularExpression() is fully anchored.
+    To get a regular expression that is not anchored, pass
+    QRegularExpression::UnanchoredWildcardConversion as the conversion
+    options:
+
+    \snippet code/doc_src_port_from_qregexp.cpp 6
+
+    \section3 Minimal matching
+
+    QRegExp::setMinimal() implemented minimal matching by simply reversing the
+    greediness of the quantifiers (QRegExp did not support lazy quantifiers,
+    like \c{*?}, \c{+?}, etc.). QRegularExpression instead does support greedy,
+    lazy, and possessive quantifiers. The QRegularExpression::InvertedGreedinessOption
+    pattern option can be useful to emulate the effects of QRegExp::setMinimal():
+    if enabled, it inverts the greediness of quantifiers (greedy ones become
+    lazy and vice versa).
+
+    \section3 Caret modes
+
+    The QRegularExpression::AnchorAtOffsetMatchOption match option can be used to
+    emulate the QRegExp::CaretAtOffset behavior. There is no equivalent for the
+    other QRegExp::CaretMode modes.
+
+//! [porting-to-qregularexpression]

doc/global/includes/examples-run.qdocinc

@@ -0,0 +1,5 @@
+\section1 Running the Example
+
+To run the example from \l{Qt Creator Manual}{Qt Creator}, open the \uicontrol Welcome
+mode and select the example from \uicontrol Examples. For more information, visit
+\l{Qt Creator: Building and Running an Example}{Building and Running an Example}.

doc/global/includes/module-use.qdocinc

@@ -0,0 +1,64 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [using qt module]
+
+    \section1 Using the Module
+
+    Using a Qt module requires linking against the module library, either
+    directly or through other dependencies. Several build tools have dedicated
+    support for this, including \l{CMake Documentation}{CMake} and
+    \l{qmake}.
+
+    \section2 Building with CMake
+
+    Use the \c{find_package()} command to locate the needed module components in
+    the \c{Qt6} package:
+
+//! [using qt module]
+
+//! [using the c++ api]
+    Using a Qt module's C++ API requires linking against the module library,
+    either directly or through other dependencies. Several build tools have
+    dedicated support for this, including \l{CMake Documentation}{CMake} and
+    \l{qmake}.
+//! [using the c++ api]
+
+//! [using the qml api]
+    The QML types of the module are available through the \c \1 import. To use
+    the types, add the following import statement to your .qml file:
+
+    \qml
+    import \1
+    \endqml
+//! [using the qml api]
+
+//! [building with qmake]
+
+    \section2 Building with qmake
+
+    To configure the module for building with qmake, add the module as a value
+    of the \c QT variable in the project's .pro file:
+
+//! [building with qmake]
+
+//! [building_with_qmake]
+    To configure the module for building with qmake, add the module as a value
+    of the \c QT variable in the project's .pro file:
+
+    \code
+    QT += \1
+    \endcode
+//! [building_with_qmake]
+
+//! [building with cmake]
+    Use the \c {find_package()} command to locate the needed module component
+    in the \c {Qt6} package:
+
+    \code
+    find_package(Qt6 REQUIRED COMPONENTS \1)
+    target_link_libraries(mytarget PRIVATE Qt6::\1)
+    \endcode
+
+    For more details, see the \l {Build with CMake} overview.
+//! [building with cmake]

doc/global/includes/standardpath/functiondocs.qdocinc

@@ -0,0 +1,108 @@
+// Copyright (C) 2019 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [displayName]
+
+    Returns a localized display name for the given location \a type
+    or an empty QString if no relevant location can be found.
+
+//! [displayName]
+
+
+//! [findExecutable]
+
+    Finds the executable named \a executableName in the specified
+    \a paths, or the system paths if paths is empty.
+
+    On most operating systems the system path is determined by the
+    \c PATH environment variable. The directories where to search for
+    the executable can be set in the paths argument. To search in
+    both your own paths and the system paths, call findExecutable
+    twice, once with paths set and once with paths empty.
+    Symlinks are not resolved in order to preserve behavior for the
+    case of executables whose behavior depends on the name they are
+    invoked with
+    .
+    \note On Windows, the usual executable extensions (from the PATHEXT
+    environment variable) are automatically appended. For example, the
+    findExecutable("foo") call finds \c foo.exe or \c foo.bat if
+    present.
+
+    Returns the absolute file path to the executable, or an empty
+    string if not found.
+
+    If the given \n executableName is an absolute path pointing to
+    an executable its clean path is returned.
+
+//! [findExecutable]
+
+//! [locate]
+
+    Finds a file or directory called \a fileName in the standard
+    locations for \a type.
+
+    The \a options flag lets you specify whether to look for files
+    or directories. By default, this flag is set to \c LocateFile.
+
+    Returns the absolute path to the first file or directory found,
+    otherwise returns an empty string.
+
+//! [locate]
+
+//! [locateAll]
+
+    Finds all files or directories by the name, \a fileName, in the
+    standard locations for \a type.
+
+    The \a options flag lets you specify whether to look for files
+    or directories. By default, this flag is set to \c LocateFile.
+
+    Returns the list of all the files that were found.
+
+//! [locateAll]
+
+//! [setTestModeEnabled]
+
+    If \a testMode is \c true, this enables a special "test mode" in
+    QStandardPaths, which changes writable locations to point to
+    test directories. This prevents auto tests from reading
+    or writing to the current user's configuration.
+
+    It affects the locations into which test programs might write
+    files: \c GenericDataLocation, \c AppDataLocation, \c ConfigLocation,
+    \c GenericConfigLocation, \c AppConfigLocation,
+    \c GenericCacheLocation, and \c CacheLocation. Other locations
+    are not affected.
+
+    On Unix, \c XDG_DATA_HOME is set to \c{~/.qttest/share},
+    \c XDG_CONFIG_HOME is set to \c{~/.qttest/config}, and
+    \c XDG_CACHE_HOME is set to \c{~/.qttest/cache}.
+
+    On macOS, data goes to \c{~/.qttest/Application Support},
+    cache goes to \c{~/.qttest/Cache}, and config goes to
+    \c{~/.qttest/Preferences}.
+
+    On Windows, everything goes to a "qttest" directory under
+    \c{%APPDATA%}.
+
+//! [setTestModeEnabled]
+
+//! [standardLocations]
+
+    Returns all the directories where files of \a type belong.
+
+    The list of directories is sorted from high to low priority,
+    starting with writableLocation() if it can be determined.
+    This list is empty if no locations for type are defined.
+
+//! [standardLocations]
+
+//! [writableLocation]
+
+    Returns the directory where files of \a type should be written to,
+    or an empty string if the location cannot be determined.
+
+    \note The storage location returned may not exist; that is,
+    it may need to be created by the system or the user.
+
+//! [writableLocation]