whytofly
/
qt6-bb10
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: Move literal code block to a separate file 

We need to override this snippet for the documentation
we generate for Qt for Python, and it is easier to have
it on a separate file.

Task-number: PYSIDE-801
Task-number: PYSIDE-691
Change-Id: Ideb5b6af25024279f167137d3b65660bb9c96a7e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
bb10
Cristian Maureira-Fredes 2018-09-03 14:02:13 +02:00
parent 02a2144427
commit 1f6bfc2207
114 changed files with 3627 additions and 1647 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/corelib/animation/qparallelanimationgroup.cpp
View File

@ -53,13 +53,7 @@
You can treat QParallelAnimationGroup as any other QAbstractAnimation,
e.g., pause, resume, or add it to other animation groups.
\code
QParallelAnimationGroup *group = new QParallelAnimationGroup;
group->addAnimation(anim1);
group->addAnimation(anim2);
group->start();
\endcode
\snippet code/src_corelib_animation_qparallelanimationgroup.cpp 0
In this example, \c anim1 and \c anim2 are two
\l{QPropertyAnimation}s that have already been set up.

9
src/corelib/animation/qpropertyanimation.cpp
View File

@ -56,14 +56,7 @@
makes it possible to animate many of Qt's widgets. Let's look at
an example:
\code
QPropertyAnimation *animation = new QPropertyAnimation(myWidget, "geometry");
animation->setDuration(10000);
animation->setStartValue(QRect(0, 0, 100, 30));
animation->setEndValue(QRect(250, 250, 100, 30));
animation->start();
\endcode
\snippet code/src_corelib_animation_qpropertyanimation.cpp 0
The property name and the QObject instance of which property
should be animated are passed to the constructor. You can then

9
src/corelib/animation/qsequentialanimationgroup.cpp
View File

@ -61,14 +61,7 @@
groups. You can also call addPause() or insertPause() to add a
pause to a sequential animation group.
\code
QSequentialAnimationGroup *group = new QSequentialAnimationGroup;
group->addAnimation(anim1);
group->addAnimation(anim2);
group->start();
\endcode
\snippet code/src_corelib_animation_qsequentialanimationgroup.cpp 0
In this example, \c anim1 and \c anim2 are two already set up
\l{QPropertyAnimation}s.

14
src/corelib/animation/qvariantanimation.cpp
View File

@ -118,15 +118,7 @@ QT_BEGIN_NAMESPACE
and the current progress.
Example:
\code
QVariant myColorInterpolator(const QColor &start, const QColor &end, qreal progress)
{
...
return QColor(...);
}
...
qRegisterAnimationInterpolator<QColor>(myColorInterpolator);
\endcode
\snippet code/src_corelib_animation_qvariantanimation.cpp 0
Another option is to reimplement interpolated(), which returns
interpolation values for the value being interpolated.
@ -418,9 +410,7 @@ static QBasicMutex registeredInterpolatorsMutex;
This is a typedef for a pointer to a function with the following
signature:
\code
QVariant myInterpolator(const QVariant &from, const QVariant &to, qreal progress);
\endcode
\snippet code/src_corelib_animation_qvariantanimation.cpp 1
*/

46
src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp Normal file
View File

@ -0,0 +1,46 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QParallelAnimationGroup *group = new QParallelAnimationGroup;
group->addAnimation(anim1);
group->addAnimation(anim2);
group->start();
//! [0]

48
src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp Normal file
View File

@ -0,0 +1,48 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QPropertyAnimation *animation = new QPropertyAnimation(myWidget, "geometry");
animation->setDuration(10000);
animation->setStartValue(QRect(0, 0, 100, 30));
animation->setEndValue(QRect(250, 250, 100, 30));
animation->start();
//! [0]

47
src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp Normal file
View File

@ -0,0 +1,47 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QSequentialAnimationGroup *group = new QSequentialAnimationGroup;
group->addAnimation(anim1);
group->addAnimation(anim2);
group->start();
//! [0]

52
src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp Normal file
View File

@ -0,0 +1,52 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QVariant myColorInterpolator(const QColor &start, const QColor &end, qreal progress)
{
...
return QColor(...);
}
...
qRegisterAnimationInterpolator<QColor>(myColorInterpolator);
//! [0]
//! [1]
QVariant myInterpolator(const QVariant &from, const QVariant &to, qreal progress);
//! [1]

61
src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp
View File

@ -725,3 +725,64 @@ bool readConfiguration(const QFile &file)
#include <QtGui>
#endif
//! [qt-version-check]
//! [is-empty]
qgetenv(varName).isEmpty()
//! [is-empty]
//! [to-int]
qgetenv(varName).toInt(ok, 0)
//! [to-int]
//! [is-null]
!qgetenv(varName).isNull()
//! [is-null]
//! [as-const-0]
QString s = ...;
for (QChar ch : s) // detaches 's' (performs a deep-copy if 's' was shared)
process(ch);
for (QChar ch : qAsConst(s)) // ok, no detach attempt
process(ch);
//! [as-const-0]
//! [as-const-1]
const QString s = ...;
for (QChar ch : s) // ok, no detach attempt on const objects
process(ch);
//! [as-const-1]
//! [as-const-2]
for (QChar ch : funcReturningQString())
process(ch); // OK, the returned object is kept alive for the loop's duration
//! [as-const-2]
//! [as-const-3]
for (QChar ch : qAsConst(funcReturningQString()))
process(ch); // ERROR: ch is copied from deleted memory
//! [as-const-3]
//! [as-const-4]
for (QChar ch : qAsConst(funcReturningQString()))
process(ch); // ERROR: ch is copied from deleted memory
//! [as-const-4]
//! [qterminate]
try { expr; } catch(...) { qTerminate(); }
//! [qterminate]
//! [qdecloverride]
// generate error if this doesn't actually override anything:
virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_OVERRIDE;
//! [qdecloverride]
//! [qdeclfinal-1]
// more-derived classes no longer permitted to override this:
virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_FINAL;
//! [qdeclfinal-1]
//! [qdeclfinal-2]
class QRect Q_DECL_FINAL { // cannot be derived from
// ...
};
//! [qdeclfinal-2]

42
src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp Normal file
View File

@ -0,0 +1,42 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz t} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}"
//! [0]

45
src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp Normal file
View File

@ -0,0 +1,45 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
if (qFloatDistance(a, b) < (1 << 7)) { // The last 7 bits are not
// significant
// precise enough
}
//! [0]

50
src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp Normal file
View File

@ -0,0 +1,50 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QOperatingSystemVersion::current() >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 9)
//! [0]
//! [1]
auto current = QOperatingSystemVersion::current();
if (current >= QOperatingSystemVersion::OSXYosemite ||
current >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 8)) {
// returns true on macOS >= 10.10 and iOS >= 8.0, but false on macOS < 10.10 and iOS < 8.0
}
//! [1]

120
src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp Normal file
View File

@ -0,0 +1,120 @@
/****************************************************************************
**
** Copyright (C) 2018 Intel Corporation.
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
quint32 value = QRandomGenerator::global()->generate();
//! [0]
//! [1]
QRandomGenerator prng1(1234), prng2(1234);
Q_ASSERT(prng1.generate() == prng2.generate());
Q_ASSERT(prng1.generate64() == prng2.generate64());
//! [1]
//! [2]
int x = QRandomGenerator::global()->generate();
int y = QRandomGenerator::global()->generate();
int w = QRandomGenerator::global()->bounded(16384);
int h = QRandomGenerator::global()->bounded(16384);
//! [2]
//! [3]
std::uniform_real_distribution dist(1, 2.5);
return dist(*QRandomGenerator::global());
//! [3]
//! [4]
std::seed_seq sseq(seedBuffer, seedBuffer + len);
QRandomGenerator generator(sseq);
//! [4]
//! [5]
std::seed_seq sseq(begin, end);
QRandomGenerator generator(sseq);
//! [5]
//! [6]
while (z--)
generator.generate();
//! [6]
//! [7]
std::generate(begin, end, [this]() { return generate(); });
//! [7]
//! [8]
std::generate(begin, end, []() { return QRandomGenerator::global()->generate64(); });
//! [8]
//! [9]
QVector<quint32> vector;
vector.resize(16);
QRandomGenerator::fillRange(vector.data(), vector.size());
//! [9]
//! [10]
quint32 array[2];
QRandomGenerator::fillRange(array);
//! [10]
//! [11]
QRandomGenerator64 rd;
return std::generate_canonical<qreal, std::numeric_limits<qreal>::digits>(rd);
//! [11]
//! [12]
return generateDouble() * highest;
//! [12]
//! [13]
quint32 v = QRandomGenerator::bounded(256);
//! [13]
//! [14]
quint32 v = QRandomGenerator::bounded(1000, 2000);
//! [14]
//! [15]
return QColor::fromRgb(QRandomGenerator::global()->generate());
//! [15]
//! [16]
qint64 value = QRandomGenerator64::generate() & std::numeric_limits<qint64>::max();
//! [16]

84
src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp Normal file
View File

@ -0,0 +1,84 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QString s;
s = "a";
qDebug().noquote() << s; // prints: a
qDebug() << s; // prints: "a"
s = "\"a\r\n\"";
qDebug() << s; // prints: "\"a\r\n\""
s = "\033"; // escape character
qDebug() << s; // prints: "\u001B"
s = "\u00AD"; // SOFT HYPHEN
qDebug() << s; // prints: "\u00AD"
s = "\u00E1"; // LATIN SMALL LETTER A WITH ACUTE
qDebug() << s; // prints: "á"
s = "a\u0301"; // "a" followed by COMBINING ACUTE ACCENT
qDebug() << s; // prints: "á";
s = "\u0430\u0301"; // CYRILLIC SMALL LETTER A followed by COMBINING ACUTE ACCENT
qDebug() << s; // prints: "а́"
//! [0]
//! [1]
QByteArray ba;
ba = "a";
qDebug().noquote() << ba; // prints: a
qDebug() << ba; // prints: "a"
ba = "\"a\r\n\"";
qDebug() << ba; // prints: "\"a\r\n\""
ba = "\033"; // escape character
qDebug() << ba; // prints: "\x1B"
ba = "\xC3\xA1";
qDebug() << ba; // prints: "\xC3\xA1"
ba = QByteArray("a\0b", 3);
qDebug() << ba // prints: "\a\x00""b"
//! [1]

82
src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp Normal file
View File

@ -0,0 +1,82 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QString defaultsBasePath = "data/";
QString defaultsPath = defaultsBasePath + "defaults.conf";
QString localizedPath = defaultsBasePath
+ QString("%1/defaults.conf").arg(QLocale().name());
if (QFile::exists(localizedPath))
defaultsPath = localizedPath;
QFile defaults(defaultsPath);
//! [0]
//! [1]
QString defaultsPath = "data/defaults.conf";
#if defined(Q_OS_ANDROID)
defaultsPath = "data/android/defaults.conf";
#elif defined(Q_OS_IOS)
defaultsPath = "data/ios/defaults.conf";
#endif
QFile defaults(defaultsPath);
//! [1]
//! [2]
QFileSelector selector;
QFile defaultsFile(selector.select("data/defaults.conf"));
//! [2]
//! [3]
data/defaults.conf
data/+android/defaults.conf
data/+ios/+en_GB/defaults.conf
//! [3]
//! [4]
images/background.png
images/+android/+en_GB/background.png
//! [4]
//! [5]
images/background.png
images/+linux/background.png
images/+windows/background.png
images/+admin/background.png
images/+admin/+linux/background.png
//! [5]

57
src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp Normal file
View File

@ -0,0 +1,57 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
<category>[.<type>] = true|false
//! [0]
//! [1]
QLoggingCategory::setFilterRules("*.debug=false\n"
"driver.usb.debug=true");
//! [1]
//! [2]
[Rules]
*.debug=false
driver.usb.debug=true
//! [2]
//! [3]
QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"
//! [3]

8
src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp
View File

@ -61,3 +61,11 @@
// as it goes out of scope.
//! [0]
}
//! [1]
QFile f(":/resources/file.txt");
QTemporaryFile::createNativeFile(f); // Returns a pointer to a temporary file
QFile f("/users/qt/file.txt");
QTemporaryFile::createNativeFile(f); // Returns 0
//! [1]

86
src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp
View File

@ -101,3 +101,89 @@ QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"
//! [7]
//! [8]
qDebug() << QUrl("main.qml").isRelative(); // true: no scheme
qDebug() << QUrl("qml/main.qml").isRelative(); // true: no scheme
qDebug() << QUrl("file:main.qml").isRelative(); // false: has "file" scheme
qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" scheme
//! [8]
//! [9]
// Absolute URL, relative path
QUrl url("file:file.txt");
qDebug() << url.isRelative(); // false: has "file" scheme
qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path
// Relative URL, absolute path
url = QUrl("/home/user/file.txt");
qDebug() << url.isRelative(); // true: has no scheme
qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute path
//! [9]
//! [10]
QUrl original("http://example.com/?q=a%2B%3Db%26c");
QUrl copy(original);
copy.setQuery(copy.query(QUrl::FullyDecoded), QUrl::DecodedMode);
qDebug() << original.toString(); // prints: http://example.com/?q=a%2B%3Db%26c
qDebug() << copy.toString(); // prints: http://example.com/?q=a+=b&c
//! [10]
//! [11]
QUrl url;
url.setScheme("ftp");
//! [11]
//! [12]
qDebug() << QUrl("file:file.txt").path(); // "file.txt"
qDebug() << QUrl("/home/user/file.txt").path(); // "/home/user/file.txt"
qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"
//! [12]
//! [13]
qDebug() << QUrl("/foo%FFbar").path();
//! [13]
//! [14]
qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"
//! [14]
//! [15]
const QUrl url("/tmp/Mambo %235%3F.mp3");
qDebug() << url.path(QUrl::FullyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::FullyEncoded); // "/tmp/Mambo%20%235%3F.mp3"
//! [15]
//! [16]
qDebug() << QUrl::fromLocalFile("file.txt"); // QUrl("file:file.txt")
qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
qDebug() << QUrl::fromLocalFile("file:file.txt"); // doesn't make sense; expects path, not url with scheme
//! [16]
//! [17]
QUrl url = QUrl::fromLocalFile("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// wrong: prints QUrl("file:file.txt"), as url already has a scheme
qDebug() << baseUrl.resolved(url);
//! [17]
//! [18]
// correct: prints QUrl("file:///home/user/file.txt")
url.setScheme(QString());
qDebug() << baseUrl.resolved(url);
//! [18]
//! [19]
QUrl url = QUrl("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// prints QUrl("file:///home/user/file.txt")
qDebug() << baseUrl.resolved(url);
//! [19]
//! [20]
qDebug() << QUrl("file:file.txt").toLocalFile(); // "file:file.txt"
qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "file:///home/user/file.txt"
qDebug() << QUrl("file.txt").toLocalFile(); // ""; wasn't a local file as it had no scheme
//! [20]

43
src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp Normal file
View File

@ -0,0 +1,43 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
//! [0]

123
src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp Normal file
View File

@ -0,0 +1,123 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
void executeOperation(int msecs)
{
QDeadlineTimer deadline(msecs);
do {
if (readFromDevice(deadline.remainingTime())
break;
waitForReadyRead(deadline);
} while (!deadline.hasExpired());
}
//! [0]
//! [1]
using namespace std::chrono;
using namespace std::chrono_literals;
QDeadlineTimer deadline(30s);
device->waitForReadyRead(deadline);
if (deadline.remainingTime<nanoseconds>() > 300ms)
cleanup();
//! [1]
//! [2]
using namespace std::chrono;
using namespace std::chrono_literals;
auto now = steady_clock::now();
QDeadlineTimer deadline(now + 1s);
Q_ASSERT(deadline == now + 1s);
//! [2]
//! [3]
using namespace std::chrono_literals;
QDeadlineTimer deadline(250ms);
//! [3]
//! [4]
using namespace std::chrono_literals;
deadline.setRemainingTime(250ms);
//! [4]
//! [5]
mutex.tryLock(deadline.remainingTime());
//! [5]
//! [6]
qint64 realTimeLeft = deadline.deadline();
if (realTimeLeft != (std::numeric_limits<qint64>::max)()) {
realTimeLeft -= QDeadlineTimer::current().deadline();
// or:
//QElapsedTimer timer;
//timer.start();
//realTimeLeft -= timer.msecsSinceReference();
}
//! [6]
//! [7]
qint64 realTimeLeft = deadline.deadlineNSecs();
if (realTimeLeft != std::numeric_limits<qint64>::max())
realTimeLeft -= QDeadlineTimer::current().deadlineNSecs();
//! [7]
//! [8]
return d1.deadlineNSecs() == d2.deadlineNSecs();
//! [8]
//! [9]
return d1.deadlineNSecs() != d2.deadlineNSecs();
//! [9]
//! [10]
return d1.deadlineNSecs() < d2.deadlineNSecs();
//! [10]
//! [11]
return d1.deadlineNSecs() <= d2.deadlineNSecs();
//! [11]
//! [12]
return d1.deadlineNSecs() > d2.deadlineNSecs();
//! [12]
//! [13]
return d1.deadlineNSecs() >= d2.deadlineNSecs();
//! [13]

19
src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp
View File

@ -147,4 +147,23 @@ method.invoke(obj,
QMetaMethod destroyedSignal = QMetaMethod::fromSignal(&QObject::destroyed);
//! [9]
//! [10]
// In the class MainWindow declaration
#ifndef Q_MOC_RUN
// define the tag text as empty, so the compiler doesn't see it
# define MY_CUSTOM_TAG
#endif
...
private slots:
MY_CUSTOM_TAG void testFunc();
//! [10]
//! [11]
MainWindow win;
win.show();
int functionIndex = win.metaObject()->indexOfSlot("testFunc()");
QMetaMethod mm = win.metaObject()->method(functionIndex);
qDebug() << mm.tag(); // prints MY_CUSTOM_TAG
//! [11]
}

13
src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp
View File

@ -538,3 +538,16 @@ QString text = MyMagicClass::tr("Sim sala bim.");
//! [explicit tr context]
QString text = QScrollBar::tr("Page up");
//! [explicit tr context]
//! [53]
{
const QSignalBlocker blocker(someQObject);
// no signals here
}
//! [53]
//! [54]
const bool wasBlocked = someQObject->blockSignals(true);
// no signals here
someQObject->blockSignals(wasBlocked);
//! [54]

52
src/corelib/doc/snippets/code/src_corelib_kernel_qtestsupport_core.cpp Normal file
View File

@ -0,0 +1,52 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtTest module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
MyObject obj;
obj.startup();
QTest::qWaitFor([&]() {
return obj.isReady();
}, 3000);
//! [0]
//! [1]
int i = 0;
while (myNetworkServerNotResponding() && i++ < 50)
QTest::qWait(250);
//! [1]

15
src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp
View File

@ -55,3 +55,18 @@ if (mime.inherits("text/plain")) {
// The file is plain text, we can display it in a QTextEdit
}
//! [0]
//! [1]
QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QLatin1String("mime/packages"),
QStandardPaths::LocateDirectory);
//! [1]
//! [2]
<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<mime-type type="application/vnd.qt.qmakeprofile">
<comment xml:lang="en">Qt qmake Profile</comment>
<glob pattern="*.pro" weight="50"/>
</mime-type>
</mime-info>
//! [2]

347
src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp Normal file
View File

@ -0,0 +1,347 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QCborValue(QCborTag(2), QByteArray("\x01\0\0\0\0\0\0\0\0", 9));
//! [0]
//! [1]
writer.startMap(4); // 4 elements in the map
writer.append(QLatin1String("label"));
writer.append(QLatin1String("journald"));
writer.append(QLatin1String("autoDetect"));
writer.append(false);
writer.append(QLatin1String("condition"));
writer.append(QLatin1String("libs.journald"));
writer.append(QLatin1String("output"));
writer.startArray(1);
writer.append(QLatin1String("privateFeature"));
writer.endArray();
writer.endMap();
//! [1]
//! [2]
QFile f("output", QIODevice::WriteOnly);
QCborStreamWriter writer(&f);
writer.startMap(0);
writer.endMap();
//! [2]
//! [3]
QByteArray encodedNumber(qint64 value)
{
QByteArray ba;
QCborStreamWriter writer(&ba);
writer.append(value);
return ba;
}
//! [3]
//! [4]
writer.append(0U);
writer.append(Q_UINT64_C(4294967296));
writer.append(std::numeric_limits<quint64>::max());
//! [4]
//! [5]
writer.append(0);
writer.append(-1);
writer.append(Q_INT64_C(4294967296));
writer.append(std::numeric_limits<qint64>::max());
//! [5]
//! [6]
writer.append(QCborNegativeInteger(1));
writer.append(QCborNegativeInteger(Q_INT64_C(4294967296)));
writer.append(QCborNegativeInteger(-quint64(std::numeric_limits<qint64>::min())));
//! [6]
//! [7]
void writeFile(QCborStreamWriter &writer, const QString &fileName)
{
QFile f(fileName);
if (f.open(QIODevice::ReadOnly))
writer.append(f.readAll());
}
//! [7]
//! [8]
writer.append(QLatin1String("Hello, World"));
//! [8]
//! [9]
void writeString(QCborStreamWriter &writer, const QString &str)
{
writer.append(str);
}
//! [9]
//! [10]
void writeRxPattern(QCborStreamWriter &writer, const QRegularExpression &rx)
{
writer.append(QCborTag(36));
writer.append(rx.pattern());
}
//! [10]
//! [11]
void writeCurrentTime(QCborStreamWriter &writer)
{
writer.append(QCborKnownTags::UnixTime_t);
writer.append(time(nullptr));
}
//! [11]
//! [12]
writer.append(QCborSimpleType::Null);
writer.append(QCborSimpleType(32));
//! [12]
//! [13]
void writeFloat(QCborStreamWriter &writer, float f)
{
qfloat16 f16 = f;
if (qIsNaN(f) || f16 == f)
writer.append(f16);
else
writer.append(f);
}
//! [13]
//! [14]
void writeFloat(QCborStreamWriter &writer, double d)
{
float f = d;
if (qIsNaN(d) || d == f)
writer.append(f);
else
writer.append(d);
}
//! [14]
//! [15]
void writeDouble(QCborStreamWriter &writer, double d)
{
float f;
if (qIsNaN(d)) {
writer.append(qfloat16(qQNaN()));
} else if (qIsInf(d)) {
writer.append(d < 0 ? -qInf() : qInf());
} else if ((f = d) == d) {
qfloat16 f16 = f;
if (f16 == f)
writer.append(f16);
else
writer.append(f);
} else {
writer.append(d);
}
}
//! [15]
//! [16]
writer.append(b ? QCborSimpleType::True : QCborSimpleType::False);
//! [16]
//! [17]
writer.append(QCborSimpleType::Null);
//! [17]
//! [18]
writer.append(QCborSimpleType::Null);
//! [18]
//! [19]
writer.append(QCborSimpleType::Undefined);
//! [19]
//! [20]
void appendList(QCborStreamWriter &writer, const QLinkedList<QString> &list)
{
writer.startArray();
for (const QString &s : list)
writer.append(s);
writer.endArray();
}
//! [20]
//! [21]
void appendList(QCborStreamWriter &writer, const QStringList &list)
{
writer.startArray(list.size());
for (const QString &s : list)
writer.append(s);
writer.endArray();
}
//! [21]
//! [22]
void appendMap(QCborStreamWriter &writer, const QLinkedList<QPair<int, QString>> &list)
{
writer.startMap();
for (const auto pair : list) {
writer.append(pair.first)
writer.append(pair.second);
}
writer.endMap();
}
//! [22]
//! [23]
void appendMap(QCborStreamWriter &writer, const QMap<int, QString> &map)
{
writer.startMap(map.size());
for (auto it = map.begin(); it != map.end(); ++it) {
writer.append(it.key());
writer.append(it.value());
}
writer.endMap();
}
//! [23]
//! [24]
void handleStream(QCborStreamReader &reader)
{
switch (reader.type())
case QCborStreamReader::UnsignedInteger:
case QCborStreamReader::NegativeInteger:
case QCborStreamReader::SimpleType:
case QCborStreamReader::Float16:
case QCborStreamReader::Float:
case QCborStreamReader::Double:
handleFixedWidth(reader);
reader.next();
break;
case QCborStreamReader::ByteArray:
case QCborStreamReader::String:
handleString(reader);
break;
case QCborStreamReader::Array:
case QCborStreamReader::Map:
reader.enterContainer();
while (reader.lastError() == QCborError::NoError)
handleStream(reader);
if (reader.lastError() == QCborError::NoError)
reader.leaveContainer();
}
}
//! [24]
//! [25]
QVariantList populateFromCbor(QCborStreamReader &reader)
{
QVariantList list;
if (reader.isLengthKnown())
list.reserve(reader.length());
reader.enterContainer();
while (reader.lastError() == QCborError::NoError && reader.hasNext())
list.append(readOneElement(reader));
if (reader.lastError() == QCborError::NoError)
reader.leaveContainer();
}
//! [25]
//! [26]
QVariantMap populateFromCbor(QCborStreamReader &reader)
{
QVariantMap map;
if (reader.isLengthKnown())
map.reserve(reader.length());
reader.enterContainer();
while (reader.lastError() == QCborError::NoError && reader.hasNext()) {
QString key = readElementAsString(reader);
map.insert(key, readOneElement(reader));
}
if (reader.lastError() == QCborError::NoError)
reader.leaveContainer();
}
//! [26]
//! [27]
QString decodeString(QCborStreamReader &reader)
{
QString result;
auto r = reader.readString();
while (r.code == QCborStreamReader::Ok) {
result += r.data;
r = reader.readString();
}
if (r.code == QCborStreamReader::Error) {
// handle error condition
result.clear();
}
return result;
}
//! [27]
//! [28]
QBytearray decodeBytearray(QCborStreamReader &reader)
{
QBytearray result;
auto r = reader.readBytearray();
while (r.code == QCborStreamReader::Ok) {
result += r.data;
r = reader.readByteArray();
}
if (r.code == QCborStreamReader::Error) {
// handle error condition
result.clear();
}
return result;
}
//! [28]
//! [29]
QCborStreamReader<qsizetype> result;
do {
qsizetype size = reader.currentStringChunkSize();
qsizetype oldsize = buffer.size();
buffer.resize(oldsize + size);
result = reader.readStringChunk(buffer.data() + oldsize, size);
} while (result.status() == QCborStreamReader::Ok);
//! [29]

69
src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp Normal file
View File

@ -0,0 +1,69 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QCborValue(uuid) == QCborValue(QCborKnownTags::Uuid, uuid.toRfc4122());
//! [0]
//! [1]
QCborValue value(QCborSimpleType(12));
//! [1]
//! [2]
value.isSimpleType(QCborSimpleType(12));
//! [2]
//! [3]
QCborValue(QUrl("https://example.com")) == QCborValue(QCborKnownTags::Url, "https://example.com");
//! [3]
//! [4]
value.toMap().value(key);
//! [4]
//! [5]
value.toMap().value(key);
//! [5]
//! [6]
if (reader.isTag() && reader.toTag() == QCborKnownTags::Signature)
reader.next();
QCborValue contents = QCborValue::fromCbor(reader);
//! [6]

48
src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp Normal file
View File

@ -0,0 +1,48 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QDataStream &operator<<(QDataStream &, const QXxx &);
QDataStream &operator>>(QDataStream &, QXxx &);
//! [0]
//! [1]
QDataStream & operator<< (QDataStream& stream, const QImage& image);
QDataStream & operator>> (QDataStream& stream, QImage& image);
//! [1]

54
src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp Normal file
View File

@ -0,0 +1,54 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
{
"Array": [
true,
999,
"string"
],
"Key": "Value",
"null": null
}
//! [0]
//! [1]
{"Array":[true,999,"string"],"Key":"Value","null":null}
//! [1]

29
src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp
View File

@ -81,3 +81,32 @@ QSemaphore sem(5); // sem.available() == 5
sem.tryAcquire(250, 1000); // sem.available() == 5, waits 1000 milliseconds and returns false
sem.tryAcquire(3, 30000); // sem.available() == 2, returns true without waiting
//! [3]
//! [4]
// ... do something that may throw or return early
sem.release();
//! [4]
//! [5]
const QSemaphoreReleaser releaser(sem);
// ... do something that may throw or early return
// implicitly calls sem.release() here and at every other return in between
//! [5]
//! [6]
{ // some scope
QSemaphoreReleaser releaser; // does nothing
// ...
if (someCondition) {
releaser = QSemaphoreReleaser(sem);
// ...
}
// ...
} // conditionally calls sem.release(), depending on someCondition
//! [6]
//! [7]
releaser.cancel(); // avoid releasing old semaphore()
releaser = QSemaphoreReleaser(sem, 42);
// now will call sem.release(42) when 'releaser' is destroyed
//! [7]

27
src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
View File

@ -470,6 +470,33 @@ ba4.size(); // Returns 6.
ba4.constData(); // Returns "ca\0r\0t" without terminating \0.
//! [48]
//! [49]
QByteArray ba("ab");
ba.repeated(4); // returns "abababab"
//! [49]
//! [50]
QByteArray macAddress = QByteArray::fromHex("123456abcdef");
macAddress.toHex(':'); // returns "12:34:56:ab:cd:ef"
macAddress.toHex(0); // returns "123456abcdef"
//! [50]
//! [51]
QByteArray text = QByteArray::fromPercentEncoding("Qt%20is%20great%33");
text.data(); // returns "Qt is great!"
//! [51]
//! [52]
QByteArray text = "{a fishy string?}";
QByteArray ba = text.toPercentEncoding("{}", "s");
qDebug(ba.constData());
// prints "{a fi%73hy %73tring%3F}"
//! [52]
//! [53]
QByteArray ba = QByteArrayLiteral("byte array contents");
//! [53]
}

46
src/corelib/doc/snippets/code/src_corelib_tools_qbytearraymatcher.cpp Normal file
View File

@ -0,0 +1,46 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
static const auto matcher = qMakeStaticByteArrayMatcher("needle");
//! [0]
//! [1]
static const auto matcher = qMakeStaticByteArrayMatcher("needle");
//! [1]

59
src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp Normal file
View File

@ -0,0 +1,59 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
MyRecord record(int row) const
{
Q_ASSERT(row >= 0 && row < count());
while (row > cache.lastIndex())
cache.append(slowFetchRecord(cache.lastIndex()+1));
while (row < cache.firstIndex())
cache.prepend(slowFetchRecord(cache.firstIndex()-1));
return cache.at(row);
}
//! [0]
//! [1]
QContiguousCache<int> cache(10);
cache.insert(INT_MAX, 1); // cache contains one value and has valid indexes, INT_MAX to INT_MAX
cache.append(2); // cache contains two values but does not have valid indexes.
cache.normalizeIndexes(); // cache has two values, 1 and 2. New first index will be in the range of 0 to capacity().
//! [1]

20
src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp
View File

@ -350,3 +350,23 @@ inline uint qHash(const std::unordered_set<int> &key, uint seed = 0)
return qHashRangeCommutative(key.begin(), key.end(), seed);
}
//! [qhashrangecommutative]
//! [29]
qHash(qMakePair(key.first, key.second), seed);
//! [29]
//! [30]
{0, 1, 2}
//! [30]
//! [31]
{1, 2, 0}
//! [31]
//! [32]
uint qHash(K key);
uint qHash(const K &key);
uint qHash(K key, uint seed);
uint qHash(const K &key, uint seed);
//! [32]

10
src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp
View File

@ -58,3 +58,13 @@ QRect r2(QPoint(100, 200), QSize(11, 16));
QRectF r1(100.0, 200.1, 11.2, 16.3);
QRectF r2(QPointF(100.0, 200.1), QSizeF(11.2, 16.3));
//! [1]
//! [2]
QRect r = {15, 51, 42, 24};
r = r.transposed(); // r == {15, 51, 24, 42}
//! [2]
//! [3]
QRectF r = {1.5, 5.1, 4.2, 2.4};
r = r.transposed(); // r == {1.5, 5.1, 2.4, 4.2}
//! [3]

8
src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp
View File

@ -360,4 +360,12 @@ QString wildcard = QRegularExpression::wildcardToRegularExpression("*.jpeg");
//! [31]
}
//! [32]
(?<day>\d\d)-(?<month>\d\d)-(?<year>\d\d\d\d) (\w+) (?<name>\w+)
//! [32]
//! [33]
("", "day", "month", "year", "", "name")
//! [33]
}

55
src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp Normal file
View File

@ -0,0 +1,55 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
class EmployeeData;
//! [0]
//! [1]
template<>
EmployeeData *QSharedDataPointer<EmployeeData>::clone()
{
return d->clone();
}
//! [1]
//! [2]
QExplicitlySharedDataPointer<Base> base(new Base);
QExplicitlySharedDataPointer<Derived> derived(base); // !!! DANGER !!!
//! [2]

146
src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp Normal file
View File

@ -0,0 +1,146 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtCore module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
class Y: public QEnableSharedFromThis<Y>
{
public:
QSharedPointer<Y> f()
{
return sharedFromThis();
}
};
int main()
{
QSharedPointer<Y> p(new Y());
QSharedPointer<Y> y = p->f();
Q_ASSERT(p == y); // p and q must share ownership
}
//! [0]
//! [1]
class ScriptInterface : public QObject
{
Q_OBJECT
// ...
public slots:
void slotCalledByScript(Y *managedBySharedPointer)
{
QSharedPointer<Y> yPtr = managedBySharedPointer->sharedFromThis();
// Some other code unrelated to scripts that expects a QSharedPointer<Y> ...
}
};
//! [1]
//! [2]
static void doDeleteLater(MyObject *obj)
{
obj->deleteLater();
}
void otherFunction()
{
QSharedPointer<MyObject> obj =
QSharedPointer<MyObject>(new MyObject, doDeleteLater);
// continue using obj
obj.clear(); // calls obj->deleteLater();
}
//! [2]
//! [3]
QSharedPointer<MyObject> obj =
QSharedPointer<MyObject>(new MyObject, &QObject::deleteLater);
//! [3]
//! [4]
if (sharedptr) { ... }
//! [4]
//! [5]
if (!sharedptr) { ... }
//! [5]
//! [6]
QSharedPointer<T> other(t); this->swap(other);
//! [6]
//! [7]
QSharedPointer<T> other(t, deleter); this->swap(other);
//! [7]
//! [8]
if (weakref) { ... }
//! [8]
//! [9]
if (!weakref) { ... }
//! [9]
//! [10]
qDebug("Tracking %p", weakref.data());
//! [10]
//! [11]
// this pointer cannot be used in another thread
// so other threads cannot delete it
QWeakPointer<int> weakref = obtainReference();
Object *obj = weakref.data();
if (obj) {
// if the pointer wasn't deleted yet, we know it can't get
// deleted by our own code here nor the functions we call
otherFunction(obj);
}
//! [11]
//! [12]
QWeakPointer<int> weakref;
// ...
QSharedPointer<int> strong = weakref.toStrongRef();
if (strong)
qDebug() << "The value is:" << *strong;
else
qDebug() << "The value has already been deleted";
//! [12]

18
src/corelib/doc/snippets/code/src_corelib_tools_qstring.cpp
View File

@ -102,3 +102,21 @@ QString plain = "#include <QtCore>"
QString html = plain.toHtmlEscaped();
// html == "#include &lt;QtCore&gt;"
//! [7]
//! [8]
QString str("ab");
str.repeated(4); // returns "abababab"
//! [8]
//! [9]
// hasAttribute takes a QString argument
if (node.hasAttribute("http-contents-length")) //...
//! [9]
//! [10]
if (node.hasAttribute(QStringLiteral(u"http-contents-length"))) //...
//! [10]
//! [11]
if (attribute.name() == QLatin1String("http-contents-length")) //...
//! [11]

51
src/corelib/doc/snippets/code/src_corelib_tools_qstringview.cpp Normal file
View File

@ -0,0 +1,51 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
void myfun1(QStringView sv); // preferred
void myfun2(const QStringView &sv); // compiles and works, but slower
//! [0]
//! [1]
void fun(QChar ch) { fun(QStringView(&ch, 1)); }
//! [1]
//! [2]
auto sv = QStringView(array, std::size(array)); // using C++17 std::size()
//! [2]

61
src/corelib/global/qglobal.cpp
View File

@ -3376,9 +3376,7 @@ QString qEnvironmentVariable(const char *varName)
Returns whether the environment variable \a varName is empty.
Equivalent to
\code
qgetenv(varName).isEmpty()
\endcode
\snippet code/src_corelib_global_qglobal.cpp is-empty
except that it's potentially much faster, and can't throw exceptions.
\sa qgetenv(), qEnvironmentVariable(), qEnvironmentVariableIsSet()
@ -3408,9 +3406,7 @@ bool qEnvironmentVariableIsEmpty(const char *varName) Q_DECL_NOEXCEPT
on the success of the conversion.
Equivalent to
\code
qgetenv(varName).toInt(ok, 0)
\endcode
\snippet code/src_corelib_global_qglobal.cpp to-int
except that it's much faster, and can't throw exceptions.
\note there's a limit on the length of the value, which is sufficient for
@ -3484,9 +3480,7 @@ int qEnvironmentVariableIntValue(const char *varName, bool *ok) Q_DECL_NOEXCEPT
Returns whether the environment variable \a varName is set.
Equivalent to
\code
!qgetenv(varName).isNull()
\endcode
\snippet code/src_corelib_global_qglobal.cpp is-null
except that it's potentially much faster, and can't throw exceptions.
\sa qgetenv(), qEnvironmentVariable(), qEnvironmentVariableIsEmpty()
@ -3662,37 +3656,21 @@ bool qunsetenv(const char *varName)
Its main use in Qt is to prevent implicitly-shared Qt containers
from detaching:
\code
QString s = ...;
for (QChar ch : s) // detaches 's' (performs a deep-copy if 's' was shared)
process(ch);
for (QChar ch : qAsConst(s)) // ok, no detach attempt
process(ch);
\endcode
\snippet code/src_corelib_global_qglobal.cpp as-const-0
Of course, in this case, you could (and probably should) have declared
\c s as \c const in the first place:
\code
const QString s = ...;
for (QChar ch : s) // ok, no detach attempt on const objects
process(ch);
\endcode
\snippet code/src_corelib_global_qglobal.cpp as-const-1
but often that is not easily possible.
It is important to note that qAsConst() does not copy its argument,
it just performs a \c{const_cast<const T&>(t)}. This is also the reason
why it is designed to fail for rvalues: The returned reference would go
stale too soon. So while this works (but detaches the returned object):
\code
for (QChar ch : funcReturningQString())
process(ch); // OK, the returned object is kept alive for the loop's duration
\endcode
\snippet code/src_corelib_global_qglobal.cpp as-const-2
this would not:
\code
for (QChar ch : qAsConst(funcReturningQString()))
process(ch); // ERROR: ch is copied from deleted memory
\endcode
\snippet code/src_corelib_global_qglobal.cpp as-const-3
To prevent this construct from compiling (and failing at runtime), qAsConst() has
a second, deleted, overload which binds to rvalues.
@ -3705,10 +3683,7 @@ bool qunsetenv(const char *varName)
\overload
This overload is deleted to prevent a dangling reference in code like
\code
for (QChar ch : qAsConst(funcReturningQString()))
process(ch); // ERROR: ch is copied from deleted memory
\endcode
\snippet code/src_corelib_global_qglobal.cpp as-const-4
*/
/*!
@ -4642,9 +4617,7 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters)
purpose. It either expands to \c expr (if Qt is compiled without
exception support or the compiler supports C++11 noexcept
semantics) or to
\code
try { expr; } catch(...) { qTerminate(); }
\endcode
\snippet code/src_corelib_global_qglobal.cpp qterminate
otherwise.
Since this macro expands to just \c expr if the compiler supports
@ -4714,10 +4687,7 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters)
The macro goes at the end of the function, usually after the
\c{const}, if any:
\code
// generate error if this doesn't actually override anything:
virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_OVERRIDE;
\endcode
\snippet code/src_corelib_global_qglobal.cpp qdecloverride
\sa Q_DECL_FINAL
*/
@ -4739,18 +4709,11 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters)
The macro goes at the end of the function, usually after the
\c{const}, if any:
\code
// more-derived classes no longer permitted to override this:
virtual void MyWidget::paintEvent(QPaintEvent*) Q_DECL_FINAL;
\endcode
\snippet code/src_corelib_global_qglobal.cpp qdeclfinal-1
For classes, it goes in front of the \c{:} in the class
definition, if any:
\code
class QRect Q_DECL_FINAL { // cannot be derived from
// ...
};
\endcode
\snippet code/src_corelib_global_qglobal.cpp qdeclfinal-2
\sa Q_DECL_OVERRIDE
*/

4
src/corelib/global/qlogging.cpp
View File

@ -2062,9 +2062,7 @@ void qErrnoWarning(int code, const char *msg, ...)
is not the default one.
Example:
\code
QT_MESSAGE_PATTERN="[%{time yyyyMMdd h:mm:ss.zzz t} %{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}] %{file}:%{line} - %{message}"
\endcode
\snippet code/src_corelib_global_qlogging.cpp 0
The default \a pattern is "%{if-category}%{category}: %{endif}%{message}".

7
src/corelib/global/qnumeric.cpp
View File

@ -130,12 +130,7 @@ static inline quint32 f2i(float f)
two 32-bit floating point numbers and all you need is an approximated 24-bit precision, you can
use this function like this:
\code
if (qFloatDistance(a, b) < (1 << 7)) { // The last 7 bits are not
// significant
// precise enough
}
\endcode
\snippet code/src_corelib_global_qnumeric.cpp 0
\sa qFuzzyCompare()
\since 5.2

12
src/corelib/global/qoperatingsystemversion.cpp
View File

@ -106,20 +106,12 @@ QT_BEGIN_NAMESPACE
major version number component of the object on the left hand side of the expression (10) is
greater than that of the object on the right (9):
\code
QOperatingSystemVersion::current() >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 9)
\endcode
\snippet code/src_corelib_global_qoperatingsystemversion.cpp 0
This allows expressions for multiple operating systems to be joined with a logical OR operator
and still work as expected. For example:
\code
auto current = QOperatingSystemVersion::current();
if (current >= QOperatingSystemVersion::OSXYosemite ||
current >= QOperatingSystemVersion(QOperatingSystemVersion::IOS, 8)) {
// returns true on macOS >= 10.10 and iOS >= 8.0, but false on macOS < 10.10 and iOS < 8.0
}
\endcode
\snippet code/src_corelib_global_qoperatingsystemversion.cpp 1
A more naive comparison algorithm might incorrectly return true on all versions of macOS,
including Mac OS 9. This behavior is achieved by overloading the comparison operators to return

81
src/corelib/global/qrandom.cpp
View File

@ -510,9 +510,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
those. The most common way of generating new values is to call the generate(),
generate64() or fillRange() functions. One would use it as:
\code
quint32 value = QRandomGenerator::global()->generate();
\endcode
\snippet code/src_corelib_global_qrandom.cpp 0
Additionally, it provides a floating-point function generateDouble() that
returns a number in the range [0, 1) (that is, inclusive of zero and
@ -525,11 +523,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
the numbers generated by the object will always be the same, as in the
following example:
\code
QRandomGenerator prng1(1234), prng2(1234);
Q_ASSERT(prng1.generate() == prng2.generate());
Q_ASSERT(prng1.generate64() == prng2.generate64());
\endcode
\snippet code/src_corelib_global_qrandom.cpp 1
The seed data takes the form of one or more 32-bit words. The ideal seed
size is approximately equal to the size of the QRandomGenerator class
@ -552,12 +546,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
For ease of use, QRandomGenerator provides a global object that can
be easily used, as in the following example:
\code
int x = QRandomGenerator::global()->generate();
int y = QRandomGenerator::global()->generate();
int w = QRandomGenerator::global()->bounded(16384);
int h = QRandomGenerator::global()->bounded(16384);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 2
\section1 System-wide random number generator
@ -645,10 +634,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
following code may be used to generate a floating-point number in the range
[1, 2.5):
\code
std::uniform_real_distribution dist(1, 2.5);
return dist(*QRandomGenerator::global());
\endcode
\snippet code/src_corelib_global_qrandom.cpp 3
\sa QRandomGenerator64, qrand()
*/
@ -688,10 +674,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
with the same seed value will produce the same number sequence.
This constructor is equivalent to:
\code
std::seed_seq sseq(seedBuffer, seedBuffer + len);
QRandomGenerator generator(sseq);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 4
\sa seed(), securelySeeded()
*/
@ -705,10 +688,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
with the same seed value will produce the same number sequence.
This constructor is equivalent to:
\code
std::seed_seq sseq(begin, end);
QRandomGenerator generator(sseq);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 5
\sa seed(), securelySeeded()
*/
@ -828,10 +808,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
Discards the next \a z entries from the sequence. This method is equivalent
to calling generate() \a z times and discarding the result, as in:
\code
while (z--)
generator.generate();
\endcode
\snippet code/src_corelib_global_qrandom.cpp 6
*/
/*!
@ -840,9 +817,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
Generates 32-bit quantities and stores them in the range between \a begin
and \a end. This function is equivalent to (and is implemented as):
\code
std::generate(begin, end, [this]() { return generate(); });
\endcode
\snippet code/src_corelib_global_qrandom.cpp 7
This function complies with the requirements for the function
\l{http://en.cppreference.com/w/cpp/numeric/random/seed_seq/generate}{\c std::seed_seq::generate},
@ -853,9 +828,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
32 bits of data. Any other bits will be zero. To fill the range with 64 bit
quantities, one can write:
\code
std::generate(begin, end, []() { return QRandomGenerator::global()->generate64(); });
\endcode
\snippet code/src_corelib_global_qrandom.cpp 8
If the range refers to contiguous memory (such as an array or the data from
a QVector), the fillRange() function may be used too.
@ -882,11 +855,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
For example, to fill a vector of 16 entries with random values, one may
write:
\code
QVector<quint32> vector;
vector.resize(16);
QRandomGenerator::fillRange(vector.data(), vector.size());
\endcode
\snippet code/src_corelib_global_qrandom.cpp 9
\sa generate()
*/
@ -901,10 +870,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
For example, to fill generate two 32-bit quantities, one may write:
\code
quint32 array[2];
QRandomGenerator::fillRange(array);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 10
It would have also been possible to make one call to generate64() and then split
the two halves of the 64-bit value.
@ -919,10 +885,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
inclusive of zero and exclusive of 1).
This function is equivalent to:
\code
QRandomGenerator64 rd;
return std::generate_canonical<qreal, std::numeric_limits<qreal>::digits>(rd);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 11
The same may also be obtained by using
\l{http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution}{\c std::uniform_real_distribution}
@ -937,9 +900,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
Generates one random double in the range between 0 (inclusive) and \a
highest (exclusive). This function is equivalent to and is implemented as:
\code
return generateDouble() * highest;
\endcode
\snippet code/src_corelib_global_qrandom.cpp 12
\sa generateDouble(), bounded()
*/
@ -956,9 +917,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
For example, to obtain a value between 0 and 255 (inclusive), one would write:
\code
quint32 v = QRandomGenerator::bounded(256);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 13
Naturally, the same could also be obtained by masking the result of generate()
to only the lower 8 bits. Either solution is as efficient.
@ -995,9 +954,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
For example, to obtain a value between 1000 (incl.) and 2000 (excl.), one
would write:
\code
quint32 v = QRandomGenerator::bounded(1000, 2000);
\endcode
\snippet code/src_corelib_global_qrandom.cpp 14
Note that this function cannot be used to obtain values in the full 32-bit
@ -1053,9 +1010,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
For example, the following creates a random RGB color:
\code
return QColor::fromRgb(QRandomGenerator::global()->generate());
\endcode
\snippet code/src_corelib_global_qrandom.cpp 15
Accesses to this object are thread-safe and it may therefore be used in any
thread without locks. The object may also be copied and the sequence
@ -1123,9 +1078,7 @@ inline QRandomGenerator::SystemGenerator &QRandomGenerator::SystemGenerator::sel
set. If you wish to cast the returned value to qint64 and keep it positive,
you should mask the sign bit off:
\code
qint64 value = QRandomGenerator64::generate() & std::numeric_limits<qint64>::max();
\endcode
\snippet code/src_corelib_global_qrandom.cpp 16
\sa QRandomGenerator, QRandomGenerator::generate64()
*/

46
src/corelib/io/qdebug.cpp
View File

@ -606,31 +606,7 @@ QDebug &QDebug::resetFormat()
clean.
Output examples:
\code
QString s;
s = "a";
qDebug().noquote() << s; // prints: a
qDebug() << s; // prints: "a"
s = "\"a\r\n\"";
qDebug() << s; // prints: "\"a\r\n\""
s = "\033"; // escape character
qDebug() << s; // prints: "\u001B"
s = "\u00AD"; // SOFT HYPHEN
qDebug() << s; // prints: "\u00AD"
s = "\u00E1"; // LATIN SMALL LETTER A WITH ACUTE
qDebug() << s; // prints: "á"
s = "a\u0301"; // "a" followed by COMBINING ACUTE ACCENT
qDebug() << s; // prints: "á";
s = "\u0430\u0301"; // CYRILLIC SMALL LETTER A followed by COMBINING ACUTE ACCENT
qDebug() << s; // prints: "а́"
\endcode
\snippet code/src_corelib_io_qdebug.cpp 0
*/
/*!
@ -690,25 +666,7 @@ QDebug &QDebug::resetFormat()
clean.
Output examples:
\code
QByteArray ba;
ba = "a";
qDebug().noquote() << ba; // prints: a
qDebug() << ba; // prints: "a"
ba = "\"a\r\n\"";
qDebug() << ba; // prints: "\"a\r\n\""
ba = "\033"; // escape character
qDebug() << ba; // prints: "\x1B"
ba = "\xC3\xA1";
qDebug() << ba; // prints: "\xC3\xA1"
ba = QByteArray("a\0b", 3);
qDebug() << ba // prints: "\a\x00""b"
\endcode
\snippet code/src_corelib_io_qdebug.cpp 1
Note how QDebug needed to close and reopen the string in the way C and C++
languages concatenate string literals so that the letter 'b' is not

44
src/corelib/io/qfileselector.cpp
View File

@ -81,27 +81,11 @@ QFileSelectorPrivate::QFileSelectorPrivate()
Consider the following example usage, where you want to use different settings files on
different locales. You might select code between locales like this:
\code
QString defaultsBasePath = "data/";
QString defaultsPath = defaultsBasePath + "defaults.conf";
QString localizedPath = defaultsBasePath
+ QString("%1/defaults.conf").arg(QLocale().name());
if (QFile::exists(localizedPath))
defaultsPath = localizedPath;
QFile defaults(defaultsPath);
\endcode
\snippet code/src_corelib_io_qfileselector.cpp 0
Similarly, if you want to pick a different data file based on target platform,
your code might look something like this:
\code
QString defaultsPath = "data/defaults.conf";
#if defined(Q_OS_ANDROID)
defaultsPath = "data/android/defaults.conf";
#elif defined(Q_OS_IOS)
defaultsPath = "data/ios/defaults.conf";
#endif
QFile defaults(defaultsPath);
\endcode
\snippet code/src_corelib_io_qfileselector.cpp 1
QFileSelector provides a convenient alternative to writing such boilerplate code, and in the
latter case it allows you to start using an platform-specific configuration without a recompile.
@ -109,27 +93,17 @@ QFileSelectorPrivate::QFileSelectorPrivate()
selecting a different file only on certain combinations of platform and locale. For example, to
select based on platform and/or locale, the code is as follows:
\code
QFileSelector selector;
QFile defaultsFile(selector.select("data/defaults.conf"));
\endcode
\snippet code/src_corelib_io_qfileselector.cpp 2
The files to be selected are placed in directories named with a \c'+' and a selector name. In the above
example you could have the platform configurations selected by placing them in the following locations:
\code
data/defaults.conf
data/+android/defaults.conf
data/+ios/+en_GB/defaults.conf
\endcode
\snippet code/src_corelib_io_qfileselector.cpp 3
To find selected files, QFileSelector looks in the same directory as the base file. If there are
any directories of the form +<selector> with an active selector, QFileSelector will prefer a file
with the same file name from that directory over the base file. These directories can be nested to
check against multiple selectors, for example:
\code
images/background.png
images/+android/+en_GB/background.png
\endcode
\snippet code/src_corelib_io_qfileselector.cpp 4
With those files available, you would select a different file on the android platform,
but only if the locale was en_GB.
@ -178,13 +152,7 @@ QFileSelectorPrivate::QFileSelectorPrivate()
credentials. The example is sorted so that the lowest matching file would be chosen if all
selectors were present:
\code
images/background.png
images/+linux/background.png
images/+windows/background.png
images/+admin/background.png
images/+admin/+linux/background.png
\endcode
\snippet code/src_corelib_io_qfileselector.cpp 5
Because extra selectors are checked before platform the \c{+admin/background.png} will be chosen
on Windows when the admin selector is set, and \c{+windows/background.png} will be chosen on

19
src/corelib/io/qloggingcategory.cpp
View File

@ -135,9 +135,7 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
flexible way. Rules are specified in text, where every line must have the
format
\code
<category>[.<type>] = true|false
\endcode
\snippet code/src_corelib_io_qloggingcategory.cpp 0
\c <category> is the name of the category, potentially with \c{*} as a
wildcard symbol as the first or last character (or at both positions).
@ -149,10 +147,7 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
Rules can be set via \l setFilterRules():
\code
QLoggingCategory::setFilterRules("*.debug=false\n"
"driver.usb.debug=true");
\endcode
\snippet code/src_corelib_io_qloggingcategory.cpp 1
Since Qt 5.3, logging rules are also
automatically loaded from the \c [Rules] section of a logging
@ -160,19 +155,13 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
configuration directory, or explicitly set in a \c QT_LOGGING_CONF
environment variable:
\code
[Rules]
*.debug=false
driver.usb.debug=true
\endcode
\snippet code/src_corelib_io_qloggingcategory.cpp 2
Since Qt 5.3, logging rules can also be specified in a \c QT_LOGGING_RULES
environment variable. And since Qt 5.6, multiple rules can also be
separated by semicolons:
\code
QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"
\endcode
\snippet code/src_corelib_io_qloggingcategory.cpp 3
Rules set by \l setFilterRules() take precedence over rules specified
in the QtProject configuration directory, and can, in turn, be

8
src/corelib/io/qtemporaryfile.cpp
View File

@ -893,13 +893,7 @@ bool QTemporaryFile::rename(const QString &newName)
For example:
\code
QFile f(":/resources/file.txt");
QTemporaryFile::createNativeFile(f); // Returns a pointer to a temporary file
QFile f("/users/qt/file.txt");
QTemporaryFile::createNativeFile(f); // Returns 0
\endcode
\snippet code/src_corelib_io_qtemporaryfile.cpp 1
\sa QFileInfo::isNativePath()
*/

86
src/corelib/io/qurl.cpp
View File

@ -116,27 +116,12 @@
Calling isRelative() will return whether or not the URL is relative.
A relative URL has no \l {scheme}. For example:
\code
qDebug() << QUrl("main.qml").isRelative(); // true: no scheme
qDebug() << QUrl("qml/main.qml").isRelative(); // true: no scheme
qDebug() << QUrl("file:main.qml").isRelative(); // false: has "file" scheme
qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" scheme
\endcode
\snippet code/src_corelib_io_qurl.cpp 8
Notice that a URL can be absolute while containing a relative path, and
vice versa:
\code
// Absolute URL, relative path
QUrl url("file:file.txt");
qDebug() << url.isRelative(); // false: has "file" scheme
qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path
// Relative URL, absolute path
url = QUrl("/home/user/file.txt");
qDebug() << url.isRelative(); // true: has no scheme
qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute path
\endcode
\snippet code/src_corelib_io_qurl.cpp 9
A relative URL can be resolved by passing it as an argument to resolved(),
which returns an absolute URL. isParentOf() is used for determining whether
@ -369,14 +354,7 @@
The following example illustrates the problem:
\code
QUrl original("http://example.com/?q=a%2B%3Db%26c");
QUrl copy(original);
copy.setQuery(copy.query(QUrl::FullyDecoded), QUrl::DecodedMode);
qDebug() << original.toString(); // prints: http://example.com/?q=a%2B%3Db%26c
qDebug() << copy.toString(); // prints: http://example.com/?q=a+=b&c
\endcode
\snippet code/src_corelib_io_qurl.cpp 10
If the two URLs were used via HTTP GET, the interpretation by the web
server would probably be different. In the first case, it would interpret
@ -1991,10 +1969,7 @@ void QUrl::setUrl(const QString &url, ParsingMode parsingMode)
\image qurl-authority2.png
To set the scheme, the following call is used:
\code
QUrl url;
url.setScheme("ftp");
\endcode
\snippet code/src_corelib_io_qurl.cpp 11
The scheme can also be empty, in which case the URL is interpreted
as relative.
@ -2569,11 +2544,7 @@ void QUrl::setPath(const QString &path, ParsingMode mode)
/*!
Returns the path of the URL.
\code
qDebug() << QUrl("file:file.txt").path(); // "file.txt"
qDebug() << QUrl("/home/user/file.txt").path(); // "/home/user/file.txt"
qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"
\endcode
\snippet code/src_corelib_io_qurl.cpp 12
The \a options argument controls how to format the path component. All
values produce an unambiguous result. With QUrl::FullyDecoded, all
@ -2588,27 +2559,18 @@ void QUrl::setPath(const QString &path, ParsingMode mode)
An example of data loss is when you have non-Unicode percent-encoded sequences
and use FullyDecoded (the default):
\code
qDebug() << QUrl("/foo%FFbar").path();
\endcode
\snippet code/src_corelib_io_qurl.cpp 13
In this example, there will be some level of data loss because the \c %FF cannot
be converted.
Data loss can also occur when the path contains sub-delimiters (such as \c +):
\code
qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"
\endcode
\snippet code/src_corelib_io_qurl.cpp 14
Other decoding examples:
\code
const QUrl url("/tmp/Mambo %235%3F.mp3");
qDebug() << url.path(QUrl::FullyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::FullyEncoded); // "/tmp/Mambo%20%235%3F.mp3"
\endcode
\snippet code/src_corelib_io_qurl.cpp 15
\sa setPath()
*/
@ -3859,40 +3821,22 @@ bool QUrl::isDetached() const
An empty \a localFile leads to an empty URL (since Qt 5.4).
\code
qDebug() << QUrl::fromLocalFile("file.txt"); // QUrl("file:file.txt")
qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
qDebug() << QUrl::fromLocalFile("file:file.txt"); // doesn't make sense; expects path, not url with scheme
\endcode
\snippet code/src_corelib_io_qurl.cpp 16
In the first line in snippet above, a file URL is constructed from a
local, relative path. A file URL with a relative path only makes sense
if there is a base URL to resolve it against. For example:
\code
QUrl url = QUrl::fromLocalFile("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// wrong: prints QUrl("file:file.txt"), as url already has a scheme
qDebug() << baseUrl.resolved(url);
\endcode
\snippet code/src_corelib_io_qurl.cpp 17
To resolve such a URL, it's necessary to remove the scheme beforehand:
\code
// correct: prints QUrl("file:///home/user/file.txt")
url.setScheme(QString());
qDebug() << baseUrl.resolved(url);
\endcode
\snippet code/src_corelib_io_qurl.cpp 18
For this reason, it is better to use a relative URL (that is, no scheme)
for relative file paths:
\code
QUrl url = QUrl("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// prints QUrl("file:///home/user/file.txt")
qDebug() << baseUrl.resolved(url);
\endcode
\snippet code/src_corelib_io_qurl.cpp 19
\sa toLocalFile(), isLocalFile(), QDir::toNativeSeparators()
*/
@ -3938,11 +3882,7 @@ QUrl QUrl::fromLocalFile(const QString &localFile)
returned value in the form found on SMB networks (for example,
"//servername/path/to/file.txt").
\code
qDebug() << QUrl("file:file.txt").toLocalFile(); // "file:file.txt"
qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "file:///home/user/file.txt"
qDebug() << QUrl("file.txt").toLocalFile(); // ""; wasn't a local file as it had no scheme
\endcode
\snippet code/src_corelib_io_qurl.cpp 20
Note: if the path component of this URL contains a non-UTF-8 binary
sequence (such as %80), the behaviour of this function is undefined.

10
src/corelib/io/qurlquery.cpp
View File

@ -129,10 +129,7 @@ QT_BEGIN_NAMESPACE
Non-standard delimiters should be chosen from among what RFC 3986 calls
"sub-delimiters". They are:
\code
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
\endcode
\snippet code/src_corelib_io_qurlquery.cpp 0
Use of other characters is not supported and may result in unexpected
behaviour. QUrlQuery does not verify that you passed a valid delimiter.
@ -570,10 +567,7 @@ QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding) const
\note Non-standard delimiters should be chosen from among what RFC 3986 calls
"sub-delimiters". They are:
\code
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
\endcode
\snippet code/src_corelib_io_qurlquery.cpp 0
Use of other characters is not supported and may result in unexpected
behaviour. This method does not verify that you passed a valid delimiter.

85
src/corelib/kernel/qdeadlinetimer.cpp
View File

@ -75,17 +75,7 @@ Q_DECL_CONST_FUNCTION static inline QPair<qint64, qint64> toSecsAndNSecs(qint64
QDeadlineTimer objects can be passed to functions being called to execute
this operation so they know how long to still operate.
\code
void executeOperation(int msecs)
{
QDeadlineTimer deadline(msecs);
do {
if (readFromDevice(deadline.remainingTime())
break;
waitForReadyRead(deadline);
} while (!deadline.hasExpired());
}
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 0
Many QDeadlineTimer functions deal with time out values, which all are
measured in milliseconds. There are two special values, the same as many
@ -125,15 +115,7 @@ Q_DECL_CONST_FUNCTION static inline QPair<qint64, qint64> toSecsAndNSecs(qint64
\c{std::chrono::time_point} objects. In addition, it is fully compatible
with the time literals from C++14, which allow one to write code as:
\code
using namespace std::chrono;
using namespace std::chrono_literals;
QDeadlineTimer deadline(30s);
device->waitForReadyRead(deadline);
if (deadline.remainingTime<nanoseconds>() > 300ms)
cleanup();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 1
As can be seen in the example above, QDeadlineTimer offers a templated
version of remainingTime() and deadline() that can be used to return
@ -145,13 +127,7 @@ Q_DECL_CONST_FUNCTION static inline QPair<qint64, qint64> toSecsAndNSecs(qint64
Also note that, due to this conversion, the deadlines will not be precise,
so the following code is not expected to compare equally:
\code
using namespace std::chrono;
using namespace std::chrono_literals;
auto now = steady_clock::now();
QDeadlineTimer deadline(now + 1s);
Q_ASSERT(deadline == now + 1s);
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 2
\sa QTime, QTimer, QDeadlineTimer, Qt::TimerType
*/
@ -246,10 +222,7 @@ QDeadlineTimer::QDeadlineTimer(qint64 msecs, Qt::TimerType type) Q_DECL_NOTHROW
This constructor can be used with C++14's user-defined literals for time, such as in:
\code
using namespace std::chrono_literals;
QDeadlineTimer deadline(250ms);
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 3
For optimization purposes, if \a remaining is zero or negative, this
function may skip obtaining the current time and may instead use a value
@ -339,10 +312,7 @@ void QDeadlineTimer::setPreciseRemainingTime(qint64 secs, qint64 nsecs, Qt::Time
This function can be used with C++14's user-defined literals for time, such as in:
\code
using namespace std::chrono_literals;
deadline.setRemainingTime(250ms);
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 4
\note Qt detects the necessary C++14 compiler support by way of the feature
test recommendations from
@ -415,9 +385,7 @@ void QDeadlineTimer::setTimerType(Qt::TimerType timerType)
lock functions in \l QMutex, \l QWaitCondition, \l QSemaphore, or
\l QReadWriteLock. For example:
\code
mutex.tryLock(deadline.remainingTime());
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 5
\sa remainingTimeNSecs(), isForever(), hasExpired()
*/
@ -469,16 +437,7 @@ qint64 QDeadlineTimer::rawRemainingTimeNSecs() const Q_DECL_NOTHROW
overdue, by subtracting QDeadlineTimer::current() or
QElapsedTimer::msecsSinceReference(), as in the following example:
\code
qint64 realTimeLeft = deadline.deadline();
if (realTimeLeft != (std::numeric_limits<qint64>::max)()) {
realTimeLeft -= QDeadlineTimer::current().deadline();
// or:
//QElapsedTimer timer;
//timer.start();
//realTimeLeft -= timer.msecsSinceReference();
}
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 6
\note Timers that were created as expired have an indetermine time point in
the past as their deadline, so the above calculation may not work.
@ -505,11 +464,7 @@ qint64 QDeadlineTimer::deadline() const Q_DECL_NOTHROW
overdue, by subtracting QDeadlineTimer::current(), as in the following
example:
\code
qint64 realTimeLeft = deadline.deadlineNSecs();
if (realTimeLeft != std::numeric_limits<qint64>::max())
realTimeLeft -= QDeadlineTimer::current().deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 7
\note Timers that were created as expired have an indetermine time point in
the past as their deadline, so the above calculation may not work.
@ -614,9 +569,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
same, false otherwise. The timer type used to create the two deadlines is
ignored. This function is equivalent to:
\code
return d1.deadlineNSecs() == d2.deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 8
\note comparing QDeadlineTimer objects with different timer types is
not supported and may result in unpredictable behavior.
@ -630,9 +583,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
diferent, false otherwise. The timer type used to create the two deadlines
is ignored. This function is equivalent to:
\code
return d1.deadlineNSecs() != d2.deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 9
\note comparing QDeadlineTimer objects with different timer types is
not supported and may result in unpredictable behavior.
@ -646,9 +597,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
d2, false otherwise. The timer type used to create the two deadlines is
ignored. This function is equivalent to:
\code
return d1.deadlineNSecs() < d2.deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 10
\note comparing QDeadlineTimer objects with different timer types is
not supported and may result in unpredictable behavior.
@ -662,9 +611,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
deadline in \a d2, false otherwise. The timer type used to create the two
deadlines is ignored. This function is equivalent to:
\code
return d1.deadlineNSecs() <= d2.deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 11
\note comparing QDeadlineTimer objects with different timer types is
not supported and may result in unpredictable behavior.
@ -678,9 +625,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
d2, false otherwise. The timer type used to create the two deadlines is
ignored. This function is equivalent to:
\code
return d1.deadlineNSecs() > d2.deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 12
\note comparing QDeadlineTimer objects with different timer types is
not supported and may result in unpredictable behavior.
@ -694,9 +639,7 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
deadline in \a d2, false otherwise. The timer type used to create the two
deadlines is ignored. This function is equivalent to:
\code
return d1.deadlineNSecs() >= d2.deadlineNSecs();
\endcode
\snippet code/src_corelib_kernel_qdeadlinetimer.cpp 13
\note comparing QDeadlineTimer objects with different timer types is
not supported and may result in unpredictable behavior.

20
src/corelib/kernel/qmetaobject.cpp
View File

@ -1996,27 +1996,11 @@ const char *QMetaMethod::typeName() const
Tag information can be added in the following
way in the function declaration:
\code
// In the class MainWindow declaration
#ifndef Q_MOC_RUN
// define the tag text as empty, so the compiler doesn't see it
# define MY_CUSTOM_TAG
#endif
...
private slots:
MY_CUSTOM_TAG void testFunc();
\endcode
\snippet code/src_corelib_kernel_qmetaobject.cpp 10
and the information can be accessed by using:
\code
MainWindow win;
win.show();
int functionIndex = win.metaObject()->indexOfSlot("testFunc()");
QMetaMethod mm = win.metaObject()->method(functionIndex);
qDebug() << mm.tag(); // prints MY_CUSTOM_TAG
\endcode
\snippet code/src_corelib_kernel_qmetaobject.cpp 11
For the moment, \c moc will extract and record all tags, but it will not
handle any of them specially. You can use the tags to annotate your methods

13
src/corelib/kernel/qobject.cpp
View File

@ -526,18 +526,9 @@ void QMetaCallEvent::placeMetaCall(QObject *object)
constructor and in the destructor it resets the state to what
it was before the constructor ran.
\code
{
const QSignalBlocker blocker(someQObject);
// no signals here
}
\endcode
\snippet code/src_corelib_kernel_qobject.cpp 53
is thus equivalent to
\code
const bool wasBlocked = someQObject->blockSignals(true);
// no signals here
someQObject->blockSignals(wasBlocked);
\endcode
\snippet code/src_corelib_kernel_qobject.cpp 54
except the code using QSignalBlocker is safe in the face of
exceptions.

14
src/corelib/kernel/qtestsupport_core.cpp
View File

@ -68,13 +68,7 @@ Q_CORE_EXPORT void QTestPrivate::qSleep(int ms)
Example:
\code
MyObject obj;
obj.startup();
QTest::qWaitFor([&]() {
return obj.isReady();
}, 3000);
\endcode
\snippet code/src_corelib_kernel_qtestsupport_core.cpp 0
The code above will wait for the object to become ready, for a
maximum of three seconds.
@ -91,11 +85,7 @@ Q_CORE_EXPORT void QTestPrivate::qSleep(int ms)
Example:
\code
int i = 0;
while (myNetworkServerNotResponding() && i++ < 50)
QTest::qWait(250);
\endcode
\snippet code/src_corelib_kernel_qtestsupport_core.cpp 1
The code above will wait until the network server is responding for a
maximum of about 12.5 seconds.

15
src/corelib/mimetypes/qmimedatabase.cpp
View File

@ -453,25 +453,14 @@ bool QMimeDatabasePrivate::inherits(const QString &mime, const QString &parent)
Applications which want to define custom MIME types need to install an
XML file into the locations searched for MIME definitions.
These locations can be queried with
\code
QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QLatin1String("mime/packages"),
QStandardPaths::LocateDirectory);
\endcode
\snippet code/src_corelib_mimetype_qmimedatabase.cpp 1
On a typical Unix system, this will be /usr/share/mime/packages/, but it is also
possible to extend the list of directories by setting the environment variable
\c XDG_DATA_DIRS. For instance adding /opt/myapp/share to \c XDG_DATA_DIRS will result
in /opt/myapp/share/mime/packages/ being searched for MIME definitions.
Here is an example of MIME XML:
\code
<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<mime-type type="application/vnd.qt.qmakeprofile">
<comment xml:lang="en">Qt qmake Profile</comment>
<glob pattern="*.pro" weight="50"/>
</mime-type>
</mime-info>
\endcode
\snippet code/src_corelib_mimetype_qmimedatabase.cpp 2
For more details about the syntax of XML MIME definitions, including defining
"magic" in order to detect MIME types based on data as well, read the

309
src/corelib/serialization/qcborstream.cpp
View File

@ -197,9 +197,7 @@ QDebug operator<<(QDebug dbg, QCborSimpleType st)
For example, the following creates a QCborValue containing a byte array
tagged with a tag 2.
\code
QCborValue(QCborTag(2), QByteArray("\x01\0\0\0\0\0\0\0\0", 9));
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 0
\sa QCborKnownTags, QCborStreamWriter::append(QCborTag),
QCborStreamReader::isTag(), QCborStreamReader::toTag(),
@ -530,25 +528,7 @@ QString QCborError::toString() const
}
\enddiv
\code
writer.startMap(4); // 4 elements in the map
writer.append(QLatin1String("label"));
writer.append(QLatin1String("journald"));
writer.append(QLatin1String("autoDetect"));
writer.append(false);
writer.append(QLatin1String("condition"));
writer.append(QLatin1String("libs.journald"));
writer.append(QLatin1String("output"));
writer.startArray(1);
writer.append(QLatin1String("privateFeature"));
writer.endArray();
writer.endMap();
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 1
\section1 CBOR support
@ -731,12 +711,7 @@ static CborError qt_cbor_encoder_write_callback(void *self, const void *data, si
The following example writes an empty map to a file:
\code
QFile f("output", QIODevice::WriteOnly);
QCborStreamWriter writer(&f);
writer.startMap(0);
writer.endMap();
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 2
QCborStreamWriter does not take ownership of \a device.
@ -755,15 +730,7 @@ QCborStreamWriter::QCborStreamWriter(QIODevice *device)
The following example writes a number to a byte array then returns
it.
\code
QByteArray encodedNumber(qint64 value)
{
QByteArray ba;
QCborStreamWriter writer(&ba);
writer.append(value);
return ba;
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 3
QCborStreamWriter does not take ownership of \a data.
*/
@ -821,11 +788,7 @@ QIODevice *QCborStreamWriter::device() const
Unsigned Integer value. In the following example, we write the values 0,
2\sup{32} and \c UINT64_MAX:
\code
writer.append(0U);
writer.append(Q_UINT64_C(4294967296));
writer.append(std::numeric_limits<quint64>::max());
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 4
\sa QCborStreamReader::isUnsignedInteger(), QCborStreamReader::toUnsignedInteger()
*/
@ -842,12 +805,7 @@ void QCborStreamWriter::append(quint64 u)
sign of the parameter. In the following example, we write the values 0, -1,
2\sup{32} and \c INT64_MAX:
\code
writer.append(0);
writer.append(-1);
writer.append(Q_INT64_C(4294967296));
writer.append(std::numeric_limits<qint64>::max());
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 5
\sa QCborStreamReader::isInteger(), QCborStreamReader::toInteger()
*/
@ -865,11 +823,7 @@ void QCborStreamWriter::append(qint64 i)
equivalent to 2\sup{64} (that is, -18,446,744,073,709,551,616).
In the following example, we write the values -1, -2\sup{32} and INT64_MIN:
\code
writer.append(QCborNegativeInteger(1));
writer.append(QCborNegativeInteger(Q_INT64_C(4294967296)));
writer.append(QCborNegativeInteger(-quint64(std::numeric_limits<qint64>::min())));
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 6
Note how this function can be used to encode numbers that cannot fit a
standard computer's 64-bit signed integer like \l qint64. That is, if \a n
@ -895,14 +849,7 @@ void QCborStreamWriter::append(QCborNegativeInteger n)
The following example will load and append the contents of a file to the
stream:
\code
void writeFile(QCborStreamWriter &writer, const QString &fileName)
{
QFile f(fileName);
if (f.open(QIODevice::ReadOnly))
writer.append(f.readAll());
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 7
As the example shows, unlike JSON, CBOR requires no escaping for binary
content.
@ -920,9 +867,7 @@ void QCborStreamWriter::append(QCborNegativeInteger n)
The following example appends a simple string to the stream:
\code
writer.append(QLatin1String("Hello, World"));
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 8
\b{Performance note}: CBOR requires that all Text Strings be encoded in
UTF-8, so this function will iterate over the characters in the string to
@ -955,12 +900,7 @@ void QCborStreamWriter::append(QLatin1String str)
The following example writes an arbitrary QString to the stream:
\code
void writeString(QCborStreamWriter &writer, const QString &str)
{
writer.append(str);
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 9
\sa QCborStreamReader::isString(), QCborStreamReader::readString()
*/
@ -979,13 +919,7 @@ void QCborStreamWriter::append(QStringView str)
In the following example, we append a CBOR Tag 36 (Regular Expression) and a
QRegularExpression's pattern to the stream:
\code
void writeRxPattern(QCborStreamWriter &writer, const QRegularExpression &rx)
{
writer.append(QCborTag(36));
writer.append(rx.pattern());
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 10
\sa QCborStreamReader::isTag(), QCborStreamReader::toTag()
*/
@ -1005,13 +939,7 @@ void QCborStreamWriter::append(QCborTag tag)
integer representing the current time to the stream, obtained using the \c
time() function:
\code
void writeCurrentTime(QCborStreamWriter &writer)
{
writer.append(QCborKnownTags::UnixTime_t);
writer.append(time(nullptr));
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 11
\sa QCborStreamReader::isTag(), QCborStreamReader::toTag()
*/
@ -1023,10 +951,7 @@ void QCborStreamWriter::append(QCborTag tag)
Type value. In the following example, we write the simple type for Null as
well as for type 32, which Qt has no support for.
\code
writer.append(QCborSimpleType::Null);
writer.append(QCborSimpleType(32));
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 12
\note Using Simple Types for which there is no specification can lead to
validation errors by the remote receiver. In addition, simple type values 24
@ -1047,16 +972,7 @@ void QCborStreamWriter::append(QCborSimpleType st)
a C++ \tt float to \c qfloat16 if there's no loss of precision and append it, or
instead append the \tt float.
\code
void writeFloat(QCborStreamWriter &writer, float f)
{
qfloat16 f16 = f;
if (qIsNaN(f) || f16 == f)
writer.append(f16);
else
writer.append(f);
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 13
\sa QCborStreamReader::isFloat16(), QCborStreamReader::toFloat16()
*/
@ -1073,16 +989,7 @@ void QCborStreamWriter::append(qfloat16 f)
a C++ \tt double to \tt float if there's no loss of precision and append it, or
instead append the \tt double.
\code
void writeFloat(QCborStreamWriter &writer, double d)
{
float f = d;
if (qIsNaN(d) || d == f)
writer.append(f);
else
writer.append(d);
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 14
\sa QCborStreamReader::isFloat(), QCborStreamReader::toFloat()
*/
@ -1104,25 +1011,7 @@ void QCborStreamWriter::append(float f)
which is expected to be taken into account by the system FPU or floating
point emulation directly.
\code
void writeDouble(QCborStreamWriter &writer, double d)
{
float f;
if (qIsNaN(d)) {
writer.append(qfloat16(qQNaN()));
} else if (qIsInf(d)) {
writer.append(d < 0 ? -qInf() : qInf());
} else if ((f = d) == d) {
qfloat16 f16 = f;
if (f16 == f)
writer.append(f16);
else
writer.append(f);
} else {
writer.append(d);
}
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 15
Determining if a double can be converted to an integral with no loss of
precision is left as an exercise to the reader.
@ -1200,9 +1089,7 @@ void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)
value or a CBOR True value. This function is equivalent to (and implemented
as):
\code
writer.append(b ? QCborSimpleType::True : QCborSimpleType::False);
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 16
\sa appendNull(), appendUndefined(),
QCborStreamReader::isBool(), QCborStreamReader::toBool()
@ -1215,9 +1102,7 @@ void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)
Appends a CBOR Null value to the stream. This function is equivalent to (and
implemented as): The parameter is ignored.
\code
writer.append(QCborSimpleType::Null);
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 17
\sa appendNull(), append(QCborSimpleType), QCborStreamReader::isNull()
*/
@ -1228,9 +1113,7 @@ void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)
Appends a CBOR Null value to the stream. This function is equivalent to (and
implemented as):
\code
writer.append(QCborSimpleType::Null);
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 18
\sa append(std::nullptr_t), append(QCborSimpleType), QCborStreamReader::isNull()
*/
@ -1241,9 +1124,7 @@ void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)
Appends a CBOR Undefined value to the stream. This function is equivalent to (and
implemented as):
\code
writer.append(QCborSimpleType::Undefined);
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 19
\sa append(QCborSimpleType), QCborStreamReader::isUndefined()
*/
@ -1260,15 +1141,7 @@ void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)
The following example appends elements from the linked list of strings
passed as input:
\code
void appendList(QCborStreamWriter &writer, const QLinkedList<QString> &list)
{
writer.startArray();
for (const QString &s : list)
writer.append(s);
writer.endArray();
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 20
\sa startArray(quint64), endArray(), startMap(), QCborStreamReader::isArray(),
QCborStreamReader::isLengthKnown()
@ -1293,15 +1166,7 @@ void QCborStreamWriter::startArray()
The following example appends all strings found in the \l QStringList passed as input:
\code
void appendList(QCborStreamWriter &writer, const QStringList &list)
{
writer.startArray(list.size());
for (const QString &s : list)
writer.append(s);
writer.endArray();
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 21
\b{Size limitations}: The parameter to this function is quint64, which would
seem to allow up to 2\sup{64}-1 elements in the array. However, both
@ -1349,17 +1214,7 @@ bool QCborStreamWriter::endArray()
The following example appends elements from the linked list of int and
string pairs passed as input:
\code
void appendMap(QCborStreamWriter &writer, const QLinkedList<QPair<int, QString>> &list)
{
writer.startMap();
for (const auto pair : list) {
writer.append(pair.first)
writer.append(pair.second);
}
writer.endMap();
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 22
\sa startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap(),
QCborStreamReader::isLengthKnown()
@ -1384,17 +1239,7 @@ void QCborStreamWriter::startMap()
The following example appends all strings found in the \l QMap passed as input:
\code
void appendMap(QCborStreamWriter &writer, const QMap<int, QString> &map)
{
writer.startMap(map.size());
for (auto it = map.begin(); it != map.end(); ++it) {
writer.append(it.key());
writer.append(it.value());
}
writer.endMap();
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 23
\b{Size limitations}: The parameter to this function is quint64, which would
seem to allow up to 2\sup{64}-1 pairs in the map. However, both
@ -1475,33 +1320,7 @@ bool QCborStreamWriter::endMap()
So a processor function typically looks like this:
\code
void handleStream(QCborStreamReader &reader)
{
switch (reader.type())
case QCborStreamReader::UnsignedInteger:
case QCborStreamReader::NegativeInteger:
case QCborStreamReader::SimpleType:
case QCborStreamReader::Float16:
case QCborStreamReader::Float:
case QCborStreamReader::Double:
handleFixedWidth(reader);
reader.next();
break;
case QCborStreamReader::ByteArray:
case QCborStreamReader::String:
handleString(reader);
break;
case QCborStreamReader::Array:
case QCborStreamReader::Map:
reader.enterContainer();
while (reader.lastError() == QCborError::NoError)
handleStream(reader);
if (reader.lastError() == QCborError::NoError)
reader.leaveContainer();
}
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 24
\section1 CBOR support
@ -1717,20 +1536,7 @@ bool QCborStreamWriter::endMap()
The following example pre-allocates a QVariantList given the array's size
for more efficient decoding:
\code
QVariantList populateFromCbor(QCborStreamReader &reader)
{
QVariantList list;
if (reader.isLengthKnown())
list.reserve(reader.length());
reader.enterContainer();
while (reader.lastError() == QCborError::NoError && reader.hasNext())
list.append(readOneElement(reader));
if (reader.lastError() == QCborError::NoError)
reader.leaveContainer();
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 25
\note The code above does not validate that the length is a sensible value.
If the input stream reports that the length is 1 billion elements, the above
@ -1754,22 +1560,7 @@ bool QCborStreamWriter::endMap()
The following example pre-allocates a QVariantMap given the map's size
for more efficient decoding:
\code
QVariantMap populateFromCbor(QCborStreamReader &reader)
{
QVariantMap map;
if (reader.isLengthKnown())
map.reserve(reader.length());
reader.enterContainer();
while (reader.lastError() == QCborError::NoError && reader.hasNext()) {
QString key = readElementAsString(reader);
map.insert(key, readOneElement(reader));
}
if (reader.lastError() == QCborError::NoError)
reader.leaveContainer();
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 26
The example above uses a function called \c readElementAsString to read the
map's keys and obtain a string. That is because CBOR maps may contain any
@ -2702,23 +2493,7 @@ bool QCborStreamReader::leaveContainer()
always loop around calling this function, even if isLengthKnown() has
is true. The typical use of this function is as follows:
\code
QString decodeString(QCborStreamReader &reader)
{
QString result;
auto r = reader.readString();
while (r.code == QCborStreamReader::Ok) {
result += r.data;
r = reader.readString();
}
if (r.code == QCborStreamReader::Error) {
// handle error condition
result.clear();
}
return result;
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 27
This function does not perform any type conversions, including from integers
or from byte arrays. Therefore, it may only be called if isString() returned
@ -2754,23 +2529,7 @@ QCborStreamReader::StringResult<QString> QCborStreamReader::_readString_helper()
always loop around calling this function, even if isLengthKnown() has
is true. The typical use of this function is as follows:
\code
QBytearray decodeBytearray(QCborStreamReader &reader)
{
QBytearray result;
auto r = reader.readBytearray();
while (r.code == QCborStreamReader::Ok) {
result += r.data;
r = reader.readByteArray();
}
if (r.code == QCborStreamReader::Error) {
// handle error condition
result.clear();
}
return result;
}
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 28
This function does not perform any type conversions, including from integers
or from strings. Therefore, it may only be called if isByteArray() is true;
@ -2840,15 +2599,7 @@ qsizetype QCborStreamReader::_currentStringChunkSize() const
This function is usually used alongside currentStringChunkSize() in a loop.
For example:
\code
QCborStreamReader<qsizetype> result;
do {
qsizetype size = reader.currentStringChunkSize();
qsizetype oldsize = buffer.size();
buffer.resize(oldsize + size);
result = reader.readStringChunk(buffer.data() + oldsize, size);
} while (result.status() == QCborStreamReader::Ok);
\endcode
\snippet code/src_corelib_serialization_qcborstream.cpp 29
Unlike readByteArray() and readString(), this function is not limited by
implementation limits of QByteArray and QString.

31
src/corelib/serialization/qcborvalue.cpp
View File

@ -102,9 +102,7 @@ QT_BEGIN_NAMESPACE
Qt types compare equal to the tag type of the same contents. In other
words, the following expression is true:
\code
QCborValue(uuid) == QCborValue(QCborKnownTags::Uuid, uuid.toRfc4122());
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 0
\section1 Undefined and null values
@ -429,9 +427,7 @@ QT_BEGIN_NAMESPACE
This function can be used with simple types not defined in the API. For
example, to create a QCborValue with simple type 12, one could write:
\code
QCborValue value(QCborSimpleType(12));
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 1
Simple types should not be used until a specification for them has been
published, since other implementations may not support them properly.
@ -702,9 +698,7 @@ QT_BEGIN_NAMESPACE
any CBOR simple type, even those for which there is no enumeration in the
API. For example, for the simple type of value 12, you could write:
\code
value.isSimpleType(QCborSimpleType(12));
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 2
\sa QCborValue::QCborValue(QCborSimpleType), isSimpleType(), isFalse(),
isTrue(), isNull, isUndefined(), toSimpleType()
@ -1163,9 +1157,7 @@ inline int QCborContainerPrivate::compareElement_helper(const QCborContainerPriv
\l{Type}{Url} and \l{Type}{Url} and its equivalent tagged representation.
So, for example, the following expression is true:
\code
QCborValue(QUrl("https://example.com")) == QCborValue(QCborKnownTags::Url, "https://example.com");
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 3
Do note that Qt types like \l QUrl and \l QDateTime will normalize and
otherwise modify their arguments. The expression above is true only because
@ -2047,9 +2039,7 @@ QCborMap QCborValue::toMap(const QCborMap &defaultValue) const
This function is equivalent to:
\code
value.toMap().value(key);
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 4
\sa operator[](qint64), QCborMap::operator[], QCborMap::value(),
QCborMap::find()
@ -2070,9 +2060,7 @@ const QCborValue QCborValue::operator[](const QString &key) const
This function is equivalent to:
\code
value.toMap().value(key);
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 5
\sa operator[](qint64), QCborMap::operator[], QCborMap::value(),
QCborMap::find()
@ -2113,12 +2101,7 @@ const QCborValue QCborValue::operator[](qint64 key) const
QCborStreamReader. For example, the following code illustrates how to skip
the CBOR signature tag from the beginning of a file:
\code
if (reader.isTag() && reader.toTag() == QCborKnownTags::Signature)
reader.next();
QCborValue contents = QCborValue::fromCbor(reader);
\endcode
\snippet code/src_corelib_serialization_qcborvalue.cpp 6
The returned value may be partially complete and indistinguishable from a
valid QCborValue even if the decoding failed. To determine if there was an

10
src/corelib/serialization/qdatastream.cpp
View File

@ -170,18 +170,12 @@ QT_BEGIN_NAMESPACE
will have appropriate stream operators declared as non-member of
the class:
\code
QDataStream &operator<<(QDataStream &, const QXxx &);
QDataStream &operator>>(QDataStream &, QXxx &);
\endcode
\snippet code/src_corelib_serialization_qdatastream.cpp 0
For example, here are the stream operators declared as non-members
of the QImage class:
\code
QDataStream & operator<< (QDataStream& stream, const QImage& image);
QDataStream & operator>> (QDataStream& stream, QImage& image);
\endcode
\snippet code/src_corelib_serialization_qdatastream.cpp 1
To see if your favorite Qt class has similar stream operators
defined, check the \b {Related Non-Members} section of the

16
src/corelib/serialization/qjsondocument.cpp
View File

@ -350,22 +350,10 @@ QByteArray QJsonDocument::toJson() const
when converting to a QJsonDocument using toJson().
\value Indented Defines human readable output as follows:
\code
{
"Array": [
true,
999,
"string"
],
"Key": "Value",
"null": null
}
\endcode
\snippet code/src_corelib_serialization_qjsondocument.cpp 0
\value Compact Defines a compact output as follows:
\code
{"Array":[true,999,"string"],"Key":"Value","null":null}
\endcode
\snippet code/src_corelib_serialization_qjsondocument.cpp 1
*/
/*!

29
src/corelib/thread/qsemaphore.cpp
View File

@ -515,10 +515,7 @@ bool QSemaphore::tryAcquire(int n, int timeout)
You can use this to reliably release a semaphore to avoid dead-lock
in the face of exceptions or early returns:
\code
// ... do something that may throw or return early
sem.release();
\endcode
\snippet code/src_corelib_thread_qsemaphore.cpp 4
If an early return is taken or an exception is thrown before the
\c{sem.release()} call is reached, the semaphore is not released,
@ -527,11 +524,7 @@ bool QSemaphore::tryAcquire(int n, int timeout)
When using RAII instead:
\code
const QSemaphoreReleaser releaser(sem);
// ... do something that may throw or early return
// implicitly calls sem.release() here and at every other return in between
\endcode
\snippet code/src_corelib_thread_qsemaphore.cpp 5
this can no longer happen, because the compiler will make sure that
the QSemaphoreReleaser destructor is always called, and therefore
@ -541,17 +534,7 @@ bool QSemaphore::tryAcquire(int n, int timeout)
from functions to transfer responsibility for releasing a semaphore
out of a function or a scope:
\code
{ // some scope
QSemaphoreReleaser releaser; // does nothing
// ...
if (someCondition) {
releaser = QSemaphoreReleaser(sem);
// ...
}
// ...
} // conditionally calls sem.release(), depending on someCondition
\endcode
\snippet code/src_corelib_thread_qsemaphore.cpp 6
A QSemaphoreReleaser can be canceled by a call to cancel(). A canceled
semaphore releaser will no longer call QSemaphore::release() in its
@ -635,11 +618,7 @@ bool QSemaphore::tryAcquire(int n, int timeout)
To enable again, assign a new QSemaphoreReleaser:
\code
releaser.cancel(); // avoid releasing old semaphore()
releaser = QSemaphoreReleaser(sem, 42);
// now will call sem.release(42) when 'releaser' is destroyed
\endcode
\snippet code/src_corelib_thread_qsemaphore.cpp 7
*/

27
src/corelib/tools/qbytearray.cpp
View File

@ -2655,10 +2655,7 @@ QList<QByteArray> QByteArray::split(char sep) const
Example:
\code
QByteArray ba("ab");
ba.repeated(4); // returns "abababab"
\endcode
\snippet code/src_corelib_tools_qbytearray.cpp 49
*/
QByteArray QByteArray::repeated(int times) const
{
@ -4732,11 +4729,7 @@ QByteArray QByteArray::toHex() const
If \a separator is not '\0', the separator character is inserted between the hex bytes.
Example:
\code
QByteArray macAddress = QByteArray::fromHex("123456abcdef");
macAddress.toHex(':'); // returns "12:34:56:ab:cd:ef"
macAddress.toHex(0); // returns "123456abcdef"
\endcode
\snippet code/src_corelib_tools_qbytearray.cpp 50
\sa fromHex()
*/
@ -4812,10 +4805,7 @@ void q_fromPercentEncoding(QByteArray *ba)
another (for instance, '_' or '=').
For example:
\code
QByteArray text = QByteArray::fromPercentEncoding("Qt%20is%20great%33");
text.data(); // returns "Qt is great!"
\endcode
\snippet code/src_corelib_tools_qbytearray.cpp 51
\note Given invalid input (such as a string containing the sequence "%G5",
which is not a valid hexadecimal number) the output will be invalid as
@ -4937,12 +4927,7 @@ void q_normalizePercentEncoding(QByteArray *ba, const char *exclude)
Example:
\code
QByteArray text = "{a fishy string?}";
QByteArray ba = text.toPercentEncoding("{}", "s");
qDebug(ba.constData());
// prints "{a fi%73hy %73tring%3F}"
\endcode
\snippet code/src_corelib_tools_qbytearray.cpp 52
The hex encoding uses the numbers 0-9 and the uppercase letters A-F.
@ -5060,9 +5045,7 @@ QByteArray QByteArray::toPercentEncoding(const QByteArray &exclude, const QByteA
For instance:
\code
QByteArray ba = QByteArrayLiteral("byte array contents");
\endcode
\snippet code/src_corelib_tools_qbytearray.cpp 53
Using QByteArrayLiteral instead of a double quoted plain C++ string literal
can significantly speed up creation of QByteArray instances from data known

8
src/corelib/tools/qbytearraymatcher.cpp
View File

@ -356,9 +356,7 @@ int qFindByteArray(
value of that function in a \c{static const auto} variable, so you don't need
to pass the \c{N} template parameter explicitly:
\code
static const auto matcher = qMakeStaticByteArrayMatcher("needle");
\endcode
\snippet code/src_corelib_tools_qbytearraymatcher.cpp 0
Then call indexIn() on the QByteArray in which you want to search, just like
with QByteArrayMatcher.
@ -430,9 +428,7 @@ int QStaticByteArrayMatcherBase::indexOfIn(const char *needle, uint nlen, const
To take full advantage of this function, assign the result to an
\c{auto} variable:
\code
static const auto matcher = qMakeStaticByteArrayMatcher("needle");
\endcode
\snippet code/src_corelib_tools_qbytearraymatcher.cpp 1
*/

21
src/corelib/tools/qcontiguouscache.cpp
View File

@ -91,19 +91,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
The simplest way of using a contiguous cache is to use the append()
and prepend().
\code
MyRecord record(int row) const
{
Q_ASSERT(row >= 0 && row < count());
while(row > cache.lastIndex())
cache.append(slowFetchRecord(cache.lastIndex()+1));
while(row < cache.firstIndex())
cache.prepend(slowFetchRecord(cache.firstIndex()-1));
return cache.at(row);
}
\endcode
\snippet code/src_corelib_tools_qcontiguouscache.cpp 0
If the cache is full then the item at the opposite end of the cache from
where the new item is appended or prepended will be removed.
@ -463,12 +451,7 @@ MyRecord record(int row) const
It is provided so that index overflows can be corrected when using the
cache as a circular buffer.
\code
QContiguousCache<int> cache(10);
cache.insert(INT_MAX, 1); // cache contains one value and has valid indexes, INT_MAX to INT_MAX
cache.append(2); // cache contains two values but does not have valid indexes.
cache.normalizeIndexes(); // cache has two values, 1 and 2. New first index will be in the range of 0 to capacity().
\endcode
\snippet code/src_corelib_tools_qcontiguouscache.cpp 1
\sa areIndexesValid(), append(), prepend()
*/

28
src/corelib/tools/qhash.cpp
View File

@ -755,9 +755,7 @@ void QHashData::checkSanity()
Types \c T1 and \c T2 must be supported by qHash().
\note The return type of this function is \e{not} the same as that of
\code
qHash(qMakePair(key.first, key.second), seed);
\endcode
\snippet code/src_corelib_tools_qhash.cpp 29
The two functions use different hashing algorithms; due to binary compatibility
constraints, we cannot change the QPair algorithm to match the std::pair one before Qt 6.
*/
@ -773,14 +771,10 @@ void QHashData::checkSanity()
The return value of this function depends on the order of elements
in the range. That means that
\code
{0, 1, 2}
\endcode
\snippet code/src_corelib_tools_qhash.cpp 30
and
\code
{1, 2, 0}
\endcode
\snippet code/src_corelib_tools_qhash.cpp 31
hash to \b{different} values. If order does not matter, for example for hash
tables, use qHashRangeCommutative() instead. If you are hashing raw
@ -812,14 +806,10 @@ void QHashData::checkSanity()
The return value of this function does not depend on the order of
elements in the range. That means that
\code
{0, 1, 2}
\endcode
\snippet code/src_corelib_tools_qhash.cpp 30
and
\code
{1, 2, 0}
\endcode
\snippet code/src_corelib_tools_qhash.cpp 31
hash to the \b{same} values. If order matters, for example, for vectors
and arrays, use qHashRange() instead. If you are hashing raw
@ -1177,13 +1167,7 @@ uint qHash(long double key, uint seed) Q_DECL_NOTHROW
For a key type \c{K}, the qHash function must have one of these signatures:
\code
uint qHash(K key);
uint qHash(const K &key);
uint qHash(K key, uint seed);
uint qHash(const K &key, uint seed);
\endcode
\snippet code/src_corelib_tools_qhash.cpp 32
The two-arguments overloads take an unsigned integer that should be used to
seed the calculation of the hash function. This seed is provided by QHash

10
src/corelib/tools/qrect.cpp
View File

@ -713,10 +713,7 @@ QRect QRect::normalized() const Q_DECL_NOTHROW
Returns a copy of the rectangle that has its width and height
exchanged:
\code
QRect r = {15, 51, 42, 24};
r = r.transposed(); // r == {15, 51, 24, 42}
\endcode
\snippet code/src_corelib_tools_qrect.cpp 2
\sa QSize::transposed()
*/
@ -1863,10 +1860,7 @@ QRectF QRectF::normalized() const Q_DECL_NOTHROW
Returns a copy of the rectangle that has its width and height
exchanged:
\code
QRectF r = {1.5, 5.1, 4.2, 2.4};
r = r.transposed(); // r == {1.5, 5.1, 2.4, 4.2}
\endcode
\snippet code/src_corelib_tools_qrect.cpp 3
\sa QSizeF::transposed()
*/

8
src/corelib/tools/qregularexpression.cpp
View File

@ -1560,15 +1560,11 @@ int QRegularExpression::captureCount() const
For instance, given the regular expression
\code
(?<day>\d\d)-(?<month>\d\d)-(?<year>\d\d\d\d) (\w+) (?<name>\w+)
\endcode
\snippet code/src_corelib_tools_qregularexpression.cpp 32
namedCaptureGroups() will return the following list:
\code
("", "day", "month", "year", "", "name")
\endcode
\snippet code/src_corelib_tools_qregularexpression.cpp 33
which corresponds to the fact that the capturing group #0 (corresponding to
the whole match) has no name, the capturing group #1 has name "day", the

17
src/corelib/tools/qshareddata.cpp
View File

@ -142,9 +142,7 @@ QT_BEGIN_NAMESPACE
would just predeclare the private subclass \c EmployeeData in \c
{employee.h} this way:
\code
class EmployeeData;
\endcode
\snippet code/src_corelib_tools_qshareddata.cpp 0
If we had done it that way here, the copy constructor shown would be
required. Since the copy constructor is trivial, you might as well
@ -396,13 +394,7 @@ QT_BEGIN_NAMESPACE
a template-specialization of this function for your own type, like
the example below:
\code
template<>
EmployeeData *QSharedDataPointer<EmployeeData>::clone()
{
return d->clone();
}
\endcode
\snippet code/src_corelib_tools_qshareddata.cpp 1
In the example above, the template specialization for the clone()
function calls the \e {EmployeeData::clone()} virtual function. A
@ -554,10 +546,7 @@ QT_BEGIN_NAMESPACE
\warning relying on such \c{static_cast} is potentially dangerous,
because it allows code like this to compile:
\code
QExplicitlySharedDataPointer<Base> base(new Base);
QExplicitlySharedDataPointer<Derived> derived(base); // !!! DANGER !!!
\endcode
\snippet code/src_corelib_tools_qshareddata.cpp 2
Starting from Qt 5.4 the cast is disabled by default. It is
possible to enable it back by defining the

108
src/corelib/tools/qsharedpointer.cpp
View File

@ -388,44 +388,14 @@
sharedFromThis() that return a QSharedPointer<T> and
QSharedPointer<const T>, depending on constness, to \c this:
\code
class Y: public QEnableSharedFromThis<Y>
{
public:
QSharedPointer<Y> f()
{
return sharedFromThis();
}
};
int main()
{
QSharedPointer<Y> p(new Y());
QSharedPointer<Y> y = p->f();
Q_ASSERT(p == y); // p and q must share ownership
}
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 0
It is also possible to get a shared pointer from an object outside of
the class itself. This is especially useful in code that provides an
interface to scripts, where it is currently not possible to use shared
pointers. For example:
\code
class ScriptInterface : public QObject
{
Q_OBJECT
// ...
public slots:
void slotCalledByScript(Y *managedBySharedPointer)
{
QSharedPointer<Y> yPtr = managedBySharedPointer->sharedFromThis();
// Some other code unrelated to scripts that expects a QSharedPointer<Y> ...
}
};
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 1
*/
/*!
@ -466,30 +436,13 @@
when the strong reference count drops to 0. This is useful,
for instance, for calling \l {QObject::}{deleteLater()} on a QObject instead:
\code
static void doDeleteLater(MyObject *obj)
{
obj->deleteLater();
}
void otherFunction()
{
QSharedPointer<MyObject> obj =
QSharedPointer<MyObject>(new MyObject, doDeleteLater);
// continue using obj
obj.clear(); // calls obj->deleteLater();
}
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 2
Note that the custom deleter function will be called with a pointer to type
\c X, even if the QSharedPointer template parameter \c T is not the same.
It is also possible to specify a member function directly, as in:
\code
QSharedPointer<MyObject> obj =
QSharedPointer<MyObject>(new MyObject, &QObject::deleteLater);
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 3
\sa clear()
*/
@ -618,9 +571,7 @@
Returns \c true if this object is not null. This function is suitable
for use in \tt if-constructs, like:
\code
if (sharedptr) { ... }
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 4
\sa isNull()
*/
@ -631,9 +582,7 @@
Returns \c true if this object is null. This function is suitable
for use in \tt if-constructs, like:
\code
if (!sharedptr) { ... }
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 5
\sa isNull()
*/
@ -766,9 +715,7 @@
Resets this QSharedPointer object to point to \a t
instead. Equivalent to:
\code
QSharedPointer<T> other(t); this->swap(other);
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 6
*/
/*!
@ -777,9 +724,7 @@
Resets this QSharedPointer object to point to \a t
instead, with the Deleter \a deleter. Equivalent to:
\code
QSharedPointer<T> other(t, deleter); this->swap(other);
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 7
*/
/*!
@ -896,9 +841,7 @@
Returns \c true if this object is not null. This function is suitable
for use in \tt if-constructs, like:
\code
if (weakref) { ... }
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 8
Note that, due to the nature of weak references, the pointer that
QWeakPointer references can become null at any moment, so
@ -914,9 +857,7 @@
Returns \c true if this object is null. This function is suitable
for use in \tt if-constructs, like:
\code
if (!weakref) { ... }
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 9
Note that, due to the nature of weak references, the pointer that
QWeakPointer references can become null at any moment, so
@ -939,9 +880,7 @@
It is ok to obtain the value of the pointer and using that value itself,
like for example in debugging statements:
\code
qDebug("Tracking %p", weakref.data());
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 10
However, dereferencing the pointer is only allowed if you can guarantee
by external means that the pointer does not get deleted. For example,
@ -950,18 +889,7 @@
If that is the case, then the following code is valid:
\code
// this pointer cannot be used in another thread
// so other threads cannot delete it
QWeakPointer<int> weakref = obtainReference();
Object *obj = weakref.data();
if (obj) {
// if the pointer wasn't deleted yet, we know it can't get
// deleted by our own code here nor the functions we call
otherFunction(obj);
}
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 11
Use this function with care.
@ -986,17 +914,7 @@
to a strong reference and, if it succeeded, it prints the value of the
integer that was held:
\code
QWeakPointer<int> weakref;
// ...
QSharedPointer<int> strong = weakref.toStrongRef();
if (strong)
qDebug() << "The value is:" << *strong;
else
qDebug() << "The value has already been deleted";
\endcode
\snippet code/src_corelib_tools_qsharedpointer.cpp 12
\sa QSharedPointer::QSharedPointer()
*/

18
src/corelib/tools/qstring.cpp
View File

@ -7966,10 +7966,7 @@ QVector<QStringRef> QString::splitRef(const QRegularExpression &re, SplitBehavio
Example:
\code
QString str("ab");
str.repeated(4); // returns "abababab"
\endcode
\snippet code/src_corelib_tools_qstring.cpp 8
*/
QString QString::repeated(int times) const
{
@ -12096,10 +12093,7 @@ QString QString::toHtmlEscaped() const
If you have code that looks like this:
\code
// hasAttribute takes a QString argument
if (node.hasAttribute("http-contents-length")) //...
\endcode
\snippet code/src_corelib_tools_qstring.cpp 9
then a temporary QString will be created to be passed as the \c{hasAttribute}
function parameter. This can be quite expensive, as it involves a memory
@ -12108,9 +12102,7 @@ QString QString::toHtmlEscaped() const
This cost can be avoided by using QStringLiteral instead:
\code
if (node.hasAttribute(QStringLiteral(u"http-contents-length"))) //...
\endcode
\snippet code/src_corelib_tools_qstring.cpp 10
In this case, QString's internal data will be generated at compile time; no
conversion or allocation will occur at runtime.
@ -12125,9 +12117,7 @@ QString QString::toHtmlEscaped() const
instance, QString::operator==() can compare to a QLatin1String
directly:
\code
if (attribute.name() == QLatin1String("http-contents-length")) //...
\endcode
\snippet code/src_corelib_tools_qstring.cpp 11
\note Some compilers have bugs encoding strings containing characters outside
the US-ASCII character set. Make sure you prefix your string with \c{u} in

13
src/corelib/tools/qstringview.cpp
View File

@ -74,19 +74,14 @@ QT_BEGIN_NAMESPACE
string literal.
QStringViews should be passed by value, not by reference-to-const:
\code
void myfun1(QStringView sv); // preferred
void myfun2(const QStringView &sv); // compiles and works, but slower
\endcode
\snippet code/src_corelib_tools_qstringview.cpp 0
If you want to give your users maximum freedom in what strings they can pass
to your function, accompany the QStringView overload with overloads for
\list
\li \e QChar: this overload can delegate to the QStringView version:
\code
void fun(QChar ch) { fun(QStringView(&ch, 1)); }
\endcode
\snippet code/src_corelib_tools_qstringview.cpp 1
even though, for technical reasons, QStringView cannot provide a
QChar constructor by itself.
\li \e QString: if you store an unmodified copy of the string and thus would
@ -291,9 +286,7 @@ QT_BEGIN_NAMESPACE
If you need the full array, use the constructor from pointer and
size instead:
\code
auto sv = QStringView(array, std::size(array)); // using C++17 std::size()
\endcode
\snippet code/src_corelib_tools_qstringview.cpp 2
\a string must remain valid for the lifetime of this string view
object.

18
src/gui/accessible/qaccessible.cpp
View File

@ -1309,14 +1309,7 @@ QColor QAccessibleInterface::backgroundColor() const
For example to notify about a focus change when re-implementing QWidget::setFocus,
the event could be used as follows:
\code
void MyWidget::setFocus(Qt::FocusReason reason)
{
// handle custom focus setting...
QAccessibleEvent event(f, QAccessible::Focus);
QAccessible::updateAccessibility(&event);
}
\endcode
\snippet code/src_gui_accessible_qaccessible.cpp 2
To enable in process screen readers, all events must be sent after the change has happened.
*/
@ -1826,14 +1819,7 @@ void QAccessibleInterface::virtual_hook(int /*id*/, void * /*data*/)
Qt's QLineEdit for example has its accessibility support
implemented in QAccessibleLineEdit.
\code
void *QAccessibleLineEdit::interface_cast(QAccessible::InterfaceType t)
{
if (t == QAccessible::TextInterface)
return static_cast<QAccessibleTextInterface*>(this);
return QAccessibleWidget::interface_cast(t);
}
\endcode
\snippet code/src_gui_accessible_qaccessible.cpp 3
\sa QAccessible::InterfaceType, QAccessibleTextInterface,
QAccessibleValueInterface, QAccessibleActionInterface,

18
src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp
View File

@ -51,3 +51,21 @@
//! [1]
typedef QAccessibleInterface* myFactoryFunction(const QString &key, QObject *);
//! [1]
//! [2]
void MyWidget::setFocus(Qt::FocusReason reason)
{
// handle custom focus setting...
QAccessibleEvent event(f, QAccessible::Focus);
QAccessible::updateAccessibility(&event);
}
//! [2]
//! [3]
void *QAccessibleLineEdit::interface_cast(QAccessible::InterfaceType t)
{
if (t == QAccessible::TextInterface)
return static_cast<QAccessibleTextInterface*>(this);
return QAccessibleWidget::interface_cast(t);
}
//! [3]

46
src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp Normal file
View File

@ -0,0 +1,46 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QVector3D result = q.rotatedVector(vector);
//! [0]
//! [1]
QVector3D result = (q * QQuaternion(0, vector) * q.conjugated()).vector();
//! [1]

49
src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp Normal file
View File

@ -0,0 +1,49 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QOpenGLBuffer buffer1(QOpenGLBuffer::IndexBuffer);
buffer1.create();
QOpenGLBuffer buffer2 = buffer1;
//! [0]
//! [1]
QOpenGLBuffer::release(QOpenGLBuffer::VertexBuffer);
//! [1]

89
src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp Normal file
View File

@ -0,0 +1,89 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtWidgets module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
GLenum error = GL_NO_ERROR;
do {
error = glGetError();
if (error != GL_NO_ERROR)
// handle the error
} while (error != GL_NO_ERROR);
//! [0]
//! [1]
QSurfaceFormat format;
// asks for a OpenGL 3.2 debug context using the Core profile
format.setMajorVersion(3);
format.setMinorVersion(2);
format.setProfile(QSurfaceFormat::CoreProfile);
format.setOption(QSurfaceFormat::DebugContext);
QOpenGLContext *context = new QOpenGLContext;
context->setFormat(format);
context->create();
//! [1]
//! [2]
QOpenGLContext *ctx = QOpenGLContext::currentContext();
QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this);
logger->initialize(); // initializes in the current context, i.e. ctx
//! [2]
//! [3]
ctx->hasExtension(QByteArrayLiteral("GL_KHR_debug"))
//! [3]
//! [4]
const QList<QOpenGLDebugMessage> messages = logger->loggedMessages();
for (const QOpenGLDebugMessage &message : messages)
qDebug() << message;
//! [4]
//! [5]
connect(logger, &QOpenGLDebugLogger::messageLogged, receiver, &LogHandler::handleLoggedMessage);
logger->startLogging();
//! [5]
//! [6]
QOpenGLDebugMessage message =
QOpenGLDebugMessage::createApplicationMessage(QStringLiteral("Custom message"));
logger->logMessage(message);
//! [6]

101
src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp Normal file
View File

@ -0,0 +1,101 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
class MyGLWindow : public QWindow, protected QOpenGLFunctions
{
Q_OBJECT
public:
MyGLWindow(QScreen *screen = 0);
protected:
void initializeGL();
void paintGL();
QOpenGLContext *m_context;
};
MyGLWindow(QScreen *screen)
: QWindow(screen), QOpenGLWidget(parent)
{
setSurfaceType(OpenGLSurface);
create();
// Create an OpenGL context
m_context = new QOpenGLContext;
m_context->create();
// Setup scene and render it
initializeGL();
paintGL();
}
void MyGLWindow::initializeGL()
{
m_context->makeCurrent(this);
initializeOpenGLFunctions();
}
//! [0]
//! [1]
void MyGLWindow::paintGL()
{
m_context->makeCurrent(this);
glActiveTexture(GL_TEXTURE1);
glBindTexture(GL_TEXTURE_2D, textureId);
...
m_context->swapBuffers(this);
m_context->doneCurrent();
}
//! [1]
//! [2]
QOpenGLFunctions glFuncs(QOpenGLContext::currentContext());
glFuncs.glActiveTexture(GL_TEXTURE1);
//! [2]
//! [3]
QOpenGLFunctions *glFuncs = QOpenGLContext::currentContext()->functions();
glFuncs->glActiveTexture(GL_TEXTURE1);
//! [3]
//! [4]
QOpenGLFunctions funcs(QOpenGLContext::currentContext());
bool npot = funcs.hasOpenGLFeature(QOpenGLFunctions::NPOTTextures);
//! [4]

28
src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp
View File

@ -68,3 +68,31 @@ mailto:user@foo.com?subject=Test&body=Just a test
//! [2]
QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode));
//! [2]
//! [3]
<key>LSApplicationQueriesSchemes</key>
<array>
<string>https</string>
</array>
//! [3]
//! [4]
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>myapp</string>
</array>
</dict>
</array>
//! [4]
//! [5]
QDesktopServices::storageLocation(QDesktopServices::DataLocation)
//! [5]
//! [6]
QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) +
"/data/organization/application"
//! [6]

59
src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp Normal file
View File

@ -0,0 +1,59 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
void Window::render()
{
QVulkanInstance *inst = vulkanInstance();
QVulkanFunctions *f = inst->functions();
...
VkResult err = f->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf);
...
}
//! [0]
//! [1]
void Window::render()
{
QVulkanInstance *inst = vulkanInstance();
QVulkanDeviceFunctions *df = inst->deviceFunctions(device);
VkResult err = df->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf);
...
}
//! [1]

135
src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp Normal file
View File

@ -0,0 +1,135 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
int main(int argc, char **argv)
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
if (!inst.create())
return 1;
...
window->setVulkanInstance(&inst);
window->show();
return app.exec();
}
//! [0]
//! [1]
QVulkanInstance inst;
// Enable validation layer, if supported. Messages go to qDebug by default.
inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation");
bool ok = inst.create();
if (!ok)
... // Vulkan not available
if (!inst.layers().contains("VK_LAYER_LUNARG_standard_validation"))
... // validation layer not available
//! [1]
//! [2]
QVulkanInstance inst;
if (inst.supportedLayers().contains("VK_LAYER_LUNARG_standard_validation"))
...
bool ok = inst.create();
...
//! [2]
//! [3]
class VulkanWindow : public QWindow
{
public:
VulkanWindow() {
setSurfaceType(VulkanSurface);
}
void exposeEvent(QExposeEvent *) {
if (isExposed()) {
if (!m_initialized) {
m_initialized = true;
// initialize device, swapchain, etc.
QVulkanInstance *inst = vulkanInstance();
QVulkanFunctions *f = inst->functions();
uint32_t devCount = 0;
f->vkEnumeratePhysicalDevices(inst->vkInstance(), &devCount, nullptr);
...
// build the first frame
render();
}
}
}
bool event(QEvent *e) {
if (e->type == QEvent::UpdateRequest)
render();
return QWindow::event(e);
}
void render() {
...
requestUpdate(); // render continuously
}
private:
bool m_initialized = false;
};
int main(int argc, char **argv)
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
if (!inst.create()) {
qWarning("Vulkan not available");
return 1;
}
VulkanWindow window;
window.showMaximized();
return app.exec();
}
//! [3]

121
src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp Normal file
View File

@ -0,0 +1,121 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
class VulkanRenderer : public QVulkanWindowRenderer
{
public:
VulkanRenderer(QVulkanWindow *w) : m_window(w) { }
void initResources() override
{
m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device());
...
}
void initSwapChainResources() override { ... }
void releaseSwapChainResources() override { ... }
void releaseResources() override { ... }
void startNextFrame() override
{
VkCommandBuffer cmdBuf = m_window->currentCommandBuffer();
...
m_devFuncs->vkCmdBeginRenderPass(...);
...
m_window->frameReady();
}
private:
QVulkanWindow *m_window;
QVulkanDeviceFunctions *m_devFuncs;
};
class VulkanWindow : public QVulkanWindow
{
public:
QVulkanWindowRenderer *createRenderer() override {
return new VulkanRenderer(this);
}
};
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
// enable the standard validation layers, when available
inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation");
if (!inst.create())
qFatal("Failed to create Vulkan instance: %d", inst.errorCode());
VulkanWindow w;
w.setVulkanInstance(&inst);
w.showMaximized();
return app.exec();
}
//! [0]
//! [1]
class Renderer {
...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
};
void Renderer::startNextFrame()
{
VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]);
...
}
//! [1]
//! [2]
class Renderer {
...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
};
void Renderer::startNextFrame()
{
const int count = m_window->concurrentFrameCount();
for (int i = 0; i < count; ++i)
m_uniformBufInfo[i] = ...
...
}
//! [2]

8
src/gui/math3d/qquaternion.cpp
View File

@ -325,15 +325,11 @@ void QQuaternion::normalize()
Rotates \a vector with this quaternion to produce a new vector
in 3D space. The following code:
\code
QVector3D result = q.rotatedVector(vector);
\endcode
\snippet code/src_gui_math3d_qquaternion.cpp 0
is equivalent to the following:
\code
QVector3D result = (q * QQuaternion(0, vector) * q.conjugated()).vector();
\endcode
\snippet code/src_gui_math3d_qquaternion.cpp 1
*/
QVector3D QQuaternion::rotatedVector(const QVector3D& vector) const
{

11
src/gui/opengl/qopenglbuffer.cpp
View File

@ -63,12 +63,7 @@ QT_BEGIN_NAMESPACE
QOpenGLBuffer objects can be copied around as a reference to the
underlying OpenGL buffer object:
\code
QOpenGLBuffer buffer1(QOpenGLBuffer::IndexBuffer);
buffer1.create();
QOpenGLBuffer buffer2 = buffer1;
\endcode
\snippet code/src_gui_opengl_qopenglbuffer.cpp 0
QOpenGLBuffer performs a shallow copy when objects are copied in this
manner, but does not implement copy-on-write semantics. The original
@ -484,9 +479,7 @@ void QOpenGLBuffer::release()
been bound to the context but wants to make sure that it
is released.
\code
QOpenGLBuffer::release(QOpenGLBuffer::VertexBuffer);
\endcode
\snippet code/src_gui_opengl_qopenglbuffer.cpp 1
*/
void QOpenGLBuffer::release(QOpenGLBuffer::Type type)
{

65
src/gui/opengl/qopengldebug.cpp
View File

@ -89,16 +89,7 @@ QT_BEGIN_NAMESPACE
call. Moreover, OpenGL errors stack up, therefore glGetError should always
be used in a loop like this:
\code
GLenum error = GL_NO_ERROR;
do {
error = glGetError();
if (error != GL_NO_ERROR)
// handle the error
} while (error != GL_NO_ERROR);
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 0
If you try to clear the error stack, make sure not just keep going until
GL_NO_ERROR is returned but also break on GL_CONTEXT_LOST as that error
@ -125,20 +116,7 @@ QT_BEGIN_NAMESPACE
to create a debug context from Qt, you must set the QSurfaceFormat::DebugContext
format option on the QSurfaceFormat used to create the QOpenGLContext object:
\code
QSurfaceFormat format;
// asks for a OpenGL 3.2 debug context using the Core profile
format.setMajorVersion(3);
format.setMinorVersion(2);
format.setProfile(QSurfaceFormat::CoreProfile);
format.setOption(QSurfaceFormat::DebugContext);
QOpenGLContext *context = new QOpenGLContext;
context->setFormat(format);
context->create();
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 1
Note that requesting a 3.2 OpenGL Core Profile is just for the example's
purposes; this class is not tied to any specific OpenGL or OpenGL ES
@ -152,24 +130,13 @@ QT_BEGIN_NAMESPACE
object), and like the other OpenGL functions in Qt you \e{must} initialize
it before usage by calling initialize() whilst there is a current OpenGL context:
\code
QOpenGLContext *ctx = QOpenGLContext::currentContext();
QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this);
logger->initialize(); // initializes in the current context, i.e. ctx
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 2
Note that the \c{GL_KHR_debug} extension \e{must} be available in the context
in order to access the messages logged by OpenGL. You can check the
presence of this extension by calling:
\code
ctx->hasExtension(QByteArrayLiteral("GL_KHR_debug"))
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 3
where \c{ctx} is a valid QOpenGLContext. If the extension is not available,
initialize() will return false.
@ -179,13 +146,7 @@ QT_BEGIN_NAMESPACE
OpenGL implementations keep an internal log of debug messages. Messages
stored in this log can be retrieved by using the loggedMessages() function:
\code
const QList<QOpenGLDebugMessage> messages = logger->loggedMessages();
for (const QOpenGLDebugMessage &message : messages)
qDebug() << message;
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 4
The internal log has a limited size; when it fills up, older messages will
get discarded to make room for the new incoming messages. When you call
@ -203,12 +164,7 @@ QT_BEGIN_NAMESPACE
you need to connect a suitable slot to the messageLogged() signal, and
start logging by calling startLogging():
\code
connect(logger, &QOpenGLDebugLogger::messageLogged, receiver, &LogHandler::handleLoggedMessage);
logger->startLogging();
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 5
Similarly, logging can be disabled at any time by calling the stopLogging()
function.
@ -259,14 +215,7 @@ QT_BEGIN_NAMESPACE
\l{QOpenGLDebugMessage::}{createThirdPartyMessage()}, and then inserting it
into the log by calling logMessage():
\code
QOpenGLDebugMessage message =
QOpenGLDebugMessage::createApplicationMessage(QStringLiteral("Custom message"));
logger->logMessage(message);
\endcode
\snippet code/src_gui_opengl_qopengldebug.cpp 6
Note that OpenGL implementations have a vendor-specific limit to the length
of the messages that can be inserted in the debug log. You can retrieve

63
src/gui/opengl/qopenglfunctions.cpp
View File

@ -90,65 +90,18 @@ void CLASS::init(QOpenGLContext *context) \
that need it. The recommended way to use QOpenGLFunctions is by
direct inheritance:
\code
class MyGLWindow : public QWindow, protected QOpenGLFunctions
{
Q_OBJECT
public:
MyGLWindow(QScreen *screen = 0);
protected:
void initializeGL();
void paintGL();
QOpenGLContext *m_context;
};
MyGLWindow(QScreen *screen)
: QWindow(screen), QOpenGLWidget(parent)
{
setSurfaceType(OpenGLSurface);
create();
// Create an OpenGL context
m_context = new QOpenGLContext;
m_context->create();
// Setup scene and render it
initializeGL();
paintGL();
}
void MyGLWindow::initializeGL()
{
m_context->makeCurrent(this);
initializeOpenGLFunctions();
}
\endcode
\snippet code/src_gui_opengl_qopenglfunctions.cpp 0
The \c{paintGL()} function can then use any of the OpenGL ES 2.0
functions without explicit resolution, such as glActiveTexture()
in the following example:
\code
void MyGLWindow::paintGL()
{
m_context->makeCurrent(this);
glActiveTexture(GL_TEXTURE1);
glBindTexture(GL_TEXTURE_2D, textureId);
...
m_context->swapBuffers(this);
m_context->doneCurrent();
}
\endcode
\snippet code/src_gui_opengl_qopenglfunctions.cpp 1
QOpenGLFunctions can also be used directly for ad-hoc invocation
of OpenGL ES 2.0 functions on all platforms:
\code
QOpenGLFunctions glFuncs(QOpenGLContext::currentContext());
glFuncs.glActiveTexture(GL_TEXTURE1);
\endcode
\snippet code/src_gui_opengl_qopenglfunctions.cpp 2
An alternative approach is to query the context's associated
QOpenGLFunctions instance. This is somewhat faster than the previous
@ -157,10 +110,7 @@ void CLASS::init(QOpenGLContext *context) \
resolving happens only once for a given context, regardless of the number of
QOpenGLFunctions instances initialized for it.
\code
QOpenGLFunctions *glFuncs = QOpenGLContext::currentContext()->functions();
glFuncs->glActiveTexture(GL_TEXTURE1);
\endcode
\snippet code/src_gui_opengl_qopenglfunctions.cpp 3
QOpenGLFunctions provides wrappers for all OpenGL ES 2.0
functions, including the common subset of OpenGL 1.x and ES
@ -175,10 +125,7 @@ void CLASS::init(QOpenGLContext *context) \
feature. For example, the following checks if non power of two
textures are available:
\code
QOpenGLFunctions funcs(QOpenGLContext::currentContext());
bool npot = funcs.hasOpenGLFeature(QOpenGLFunctions::NPOTTextures);
\endcode
\snippet code/src_gui_opengl_qopenglfunctions.cpp 4
\sa QOpenGLContext, QSurfaceFormat
*/

28
src/gui/util/qdesktopservices.cpp
View File

@ -187,12 +187,7 @@ void QOpenUrlHandlerRegistry::handlerDestroyed(QObject *handler)
\l{https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl}{canOpenURL(_:)}.
For example, the following lines enable URLs with the HTTPS scheme:
\code
<key>LSApplicationQueriesSchemes</key>
<array>
<string>https</string>
</array>
\endcode
\snippet code/src_gui_util_qdesktopservices.cpp 3
\sa setUrlHandler()
*/
@ -252,17 +247,7 @@ bool QDesktopServices::openUrl(const QUrl &url)
To use this function for receiving data from other apps on iOS you also need to
add the custom scheme to the \c CFBundleURLSchemes list in your Info.plist file:
\code
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>myapp</string>
</array>
</dict>
</array>
\endcode
\snippet code/src_gui_util_qdesktopservices.cpp 4
For more information, see the Apple Developer Documentation for
\l{https://developer.apple.com/documentation/uikit/core_app/allowing_apps_and_websites_to_link_to_your_content/communicating_with_other_apps_using_custom_urls?language=objc}{Communicating with Other Apps Using Custom URLs}.
@ -346,14 +331,9 @@ void QDesktopServices::unsetUrlHandler(const QString &scheme)
wasn't called, while in Qt 5 it defaults to the name of the executable.
Therefore, if you still need to access the Qt 4 path (for example for data migration to Qt 5), replace
\code
QDesktopServices::storageLocation(QDesktopServices::DataLocation)
\endcode
\snippet code/src_gui_util_qdesktopservices.cpp 5
with
\code
QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) +
"/data/organization/application"
\endcode
\snippet code/src_gui_util_qdesktopservices.cpp 6
(assuming an organization name and an application name were set).
*/

21
src/gui/vulkan/qvulkanfunctions.cpp
View File

@ -66,16 +66,7 @@ QT_BEGIN_NAMESPACE
The typical usage is the following:
\code
void Window::render()
{
QVulkanInstance *inst = vulkanInstance();
QVulkanFunctions *f = inst->functions();
...
VkResult err = f->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf);
...
}
\endcode
\snippet code/src_gui_vulkan_qvulkanfunctions.cpp 0
\note Windowing system interface (WSI) specifics and extensions are
excluded. This class only covers core Vulkan commands, with the exception
@ -118,15 +109,7 @@ QT_BEGIN_NAMESPACE
The typical usage is the following:
\code
void Window::render()
{
QVulkanInstance *inst = vulkanInstance();
QVulkanDeviceFunctions *df = inst->deviceFunctions(device);
VkResult err = df->vkAllocateCommandBuffers(device, &cmdBufInfo, &cmdBuf);
...
}
\endcode
\snippet code/src_gui_vulkan_qvulkanfunctions.cpp 1
The QVulkanDeviceFunctions object specific to the provided VkDevice is
created when QVulkanInstance::deviceFunctions() is first called with the

97
src/gui/vulkan/qvulkaninstance.cpp
View File

@ -97,22 +97,7 @@ QT_BEGIN_NAMESPACE
calling QWindow::setVulkanInstance(). Thus a typical application pattern is
the following:
\code
int main(int argc, char **argv)
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
if (!inst.create())
return 1;
...
window->setVulkanInstance(&inst);
window->show();
return app.exec();
}
\endcode
\snippet code/src_gui_vulkan_qvulkaninstance.cpp 0
\section1 Configuration
@ -138,31 +123,12 @@ QT_BEGIN_NAMESPACE
For example, to enable the standard validation layers, one could do the
following:
\code
QVulkanInstance inst;
// Enable validation layer, if supported. Messages go to qDebug by default.
inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation");
bool ok = inst.create();
if (!ok)
... // Vulkan not available
if (!inst.layers().contains("VK_LAYER_LUNARG_standard_validation"))
... // validation layer not available
\endcode
\snippet code/src_gui_vulkan_qvulkaninstance.cpp 1
Or, alternatively, to make decisions before attempting to create a Vulkan
instance:
\code
QVulkanInstance inst;
if (inst.supportedLayers().contains("VK_LAYER_LUNARG_standard_validation"))
...
bool ok = inst.create();
...
\endcode
\snippet code/src_gui_vulkan_qvulkaninstance.cpp 2
\section1 Adopting an Existing Instance
@ -229,62 +195,7 @@ QT_BEGIN_NAMESPACE
The following is the basic outline of creating a Vulkan-capable QWindow:
\code
class VulkanWindow : public QWindow
{
public:
VulkanWindow() {
setSurfaceType(VulkanSurface);
}
void exposeEvent(QExposeEvent *) {
if (isExposed()) {
if (!m_initialized) {
m_initialized = true;
// initialize device, swapchain, etc.
QVulkanInstance *inst = vulkanInstance();
QVulkanFunctions *f = inst->functions();
uint32_t devCount = 0;
f->vkEnumeratePhysicalDevices(inst->vkInstance(), &devCount, nullptr);
...
// build the first frame
render();
}
}
}
bool event(QEvent *e) {
if (e->type == QEvent::UpdateRequest)
render();
return QWindow::event(e);
}
void render() {
...
requestUpdate(); // render continuously
}
private:
bool m_initialized = false;
};
int main(int argc, char **argv)
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
if (!inst.create()) {
qWarning("Vulkan not available");
return 1;
}
VulkanWindow window;
window.showMaximized();
return app.exec();
}
\endcode
\snippet code/src_gui_vulkan_qvulkaninstance.cpp 3
\note In addition to expose, a well-behaving window implementation will
also have to take care of additional events like resize and

83
src/gui/vulkan/qvulkanwindow.cpp
View File

@ -74,60 +74,7 @@ Q_LOGGING_CATEGORY(lcGuiVk, "qt.vulkan")
A typical application using QVulkanWindow may look like the following:
\code
class VulkanRenderer : public QVulkanWindowRenderer
{
public:
VulkanRenderer(QVulkanWindow *w) : m_window(w) { }
void initResources() override
{
m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device());
...
}
void initSwapChainResources() override { ... }
void releaseSwapChainResources() override { ... }
void releaseResources() override { ... }
void startNextFrame() override
{
VkCommandBuffer cmdBuf = m_window->currentCommandBuffer();
...
m_devFuncs->vkCmdBeginRenderPass(...);
...
m_window->frameReady();
}
private:
QVulkanWindow *m_window;
QVulkanDeviceFunctions *m_devFuncs;
};
class VulkanWindow : public QVulkanWindow
{
public:
QVulkanWindowRenderer *createRenderer() override {
return new VulkanRenderer(this);
}
};
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QVulkanInstance inst;
// enable the standard validation layers, when available
inst.setLayers(QByteArrayList() << "VK_LAYER_LUNARG_standard_validation");
if (!inst.create())
qFatal("Failed to create Vulkan instance: %d", inst.errorCode());
VulkanWindow w;
w.setVulkanInstance(&inst);
w.showMaximized();
return app.exec();
}
\endcode
\snippet code/src_gui_vulkan_qvulkanwindow.cpp 0
As it can be seen in the example, the main patterns in QVulkanWindow usage are:
@ -2439,18 +2386,7 @@ VkFramebuffer QVulkanWindow::currentFramebuffer() const
concurrentFrameCount(). Such arrays can then be indexed by the value
returned from this function.
\code
class Renderer {
...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
};
void Renderer::startNextFrame()
{
VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]);
...
}
\endcode
\snippet code/src_gui_vulkan_qvulkanwindow.cpp 1
\note This function must only be called from within startNextFrame() and, in
case of asynchronous command generation, up until the call to frameReady().
@ -2477,20 +2413,7 @@ int QVulkanWindow::currentFrame() const
\note The value is constant for the entire lifetime of the QVulkanWindow.
\code
class Renderer {
...
VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
};
void Renderer::startNextFrame()
{
const int count = m_window->concurrentFrameCount();
for (int i = 0; i < count; ++i)
m_uniformBufInfo[i] = ...
...
}
\endcode
\snippet code/src_gui_vulkan_qvulkanwindow.cpp 2
\sa currentFrame()
*/

21
src/network/bearer/qnetworksession.cpp
View File

@ -323,11 +323,7 @@ void QNetworkSession::open()
The following example waits up to one second for the session to be opened:
\code
session->open();
if (session->waitForOpened(1000))
qDebug("Open!");
\endcode
\snippet code/src_network_bearer_qnetworksession.cpp 0
If \a msecs is -1, this function will not time out.
@ -491,20 +487,7 @@ QString QNetworkSession::errorString() const
The main purpose of this key is to determine which Internet access point is used
if the session is based on a \l{QNetworkConfiguration::ServiceNetwork}{ServiceNetwork}.
The following code snippet highlights the difference:
\code
QNetworkConfigurationManager mgr;
QNetworkConfiguration ap = mgr.defaultConfiguration();
QNetworkSession *session = new QNetworkSession(ap);
... //code activates session
QString ident = session->sessionProperty("ActiveConfiguration").toString();
if ( ap.type() == QNetworkConfiguration::ServiceNetwork ) {
Q_ASSERT( ap.identifier() != ident );
Q_ASSERT( ap.children().contains( mgr.configurationFromIdentifier(ident) ) );
} else if ( ap.type() == QNetworkConfiguration::InternetAccessPoint ) {
Q_ASSERT( ap.identifier() == ident );
}
\endcode
\snippet code/src_network_bearer_qnetworksession.cpp 1
\row
\li UserChoiceConfiguration
\li If the session \l isOpen() and is bound to a QNetworkConfiguration of type

60
src/network/doc/snippets/code/src_network_bearer_qnetworksession.cpp Normal file
View File

@ -0,0 +1,60 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtNetwork module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
session->open();
if (session->waitForOpened(1000))
qDebug("Open!");
//! [0]
//! [1]
QNetworkConfigurationManager mgr;
QNetworkConfiguration ap = mgr.defaultConfiguration();
QNetworkSession *session = new QNetworkSession(ap);
... //code activates session
QString ident = session->sessionProperty("ActiveConfiguration").toString();
if ( ap.type() == QNetworkConfiguration::ServiceNetwork ) {
Q_ASSERT( ap.identifier() != ident );
Q_ASSERT( ap.children().contains( mgr.configurationFromIdentifier(ident) ) );
} else if ( ap.type() == QNetworkConfiguration::InternetAccessPoint ) {
Q_ASSERT( ap.identifier() == ident );
}
\endcode
//! [1]

64
src/network/doc/snippets/code/src_network_kernel_qnetworkdatagram.cpp Normal file
View File

@ -0,0 +1,64 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:BSD$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** BSD License Usage
** Alternatively, you may use this file under the terms of the BSD license
** as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
** * Redistributions of source code must retain the above copyright
** notice, this list of conditions and the following disclaimer.
** * Redistributions in binary form must reproduce the above copyright
** notice, this list of conditions and the following disclaimer in
** the documentation and/or other materials provided with the
** distribution.
** * Neither the name of The Qt Company Ltd nor the names of its
** contributors may be used to endorse or promote products derived
** from this software without specific prior written permission.
**
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
void Server::readPendingDatagrams()
{
while (udpSocket->hasPendingDatagrams()) {
QNetworkDatagram datagram = udpSocket->receiveDatagram();
QByteArray replyData = processThePayload(datagram.data());
udpSocket->writeDatagram(datagram.makeReply(replyData));
}
}
//! [0]
//! [1]
udpSocket->writeDatagram(std::move(datagram).makeReply(replyData));
//! [1]

46
src/network/doc/snippets/code/src_network_kernel_qnetworkinterface.cpp Normal file
View File

@ -0,0 +1,46 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtNetwork module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QNetworkInterface::interfaceFromName(name).index()
//! [0]
//! [1]
QNetworkInterface::interfaceFromIndex(index).name()
//! [1]

53
src/network/doc/snippets/code/src_network_ssl_qsslpresharedkeyauthenticator.cpp Normal file
View File

@ -0,0 +1,53 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtNetwork module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
connect(socket, &QSslSocket::preSharedKeyAuthenticationRequired,
this, &AuthManager::handlePreSharedKeyAuthentication);
//! [0]
//! [1]
void AuthManager::handlePreSharedKeyAuthentication(QSslPreSharedKeyAuthenticator *authenticator)
{
authenticator->setIdentity("My Qt App");
const QByteArray key = deriveKey(authenticator->identityHint(), passphrase);
authenticator->setPreSharedKey(key);
}
//! [1]

15
src/network/kernel/qnetworkdatagram.cpp
View File

@ -450,16 +450,7 @@ void QNetworkDatagram::setData(const QByteArray &data)
way of responding to a datagram back to the original sender.
Example:
\code
void Server::readPendingDatagrams()
{
while (udpSocket->hasPendingDatagrams()) {
QNetworkDatagram datagram = udpSocket->receiveDatagram();
QByteArray replyData = processThePayload(datagram.data());
udpSocket->writeDatagram(datagram.makeReply(replyData));
}
}
\endcode
\snippet code/src_network_kernel_qnetworkdatagram.cpp 0
This function is especially convenient since it will automatically copy
parameters from this datagram to the new datagram as appropriate:
@ -491,9 +482,7 @@ void QNetworkDatagram::setData(const QByteArray &data)
overloads, so it is a good idea to make sure this object is rvalue, if
possible, before calling makeReply, so as to make better use of move
semantics. To achieve that, the example above would use:
\code
udpSocket->writeDatagram(std::move(datagram).makeReply(replyData));
\endcode
\snippet code/src_network_kernel_qnetworkdatagram.cpp 1
*/

8
src/network/kernel/qnetworkinterface.cpp
View File

@ -798,9 +798,7 @@ QList<QNetworkAddressEntry> QNetworkInterface::addressEntries() const
no interface with that name. This function should produce the same result
as the following code, but will probably execute faster.
\code
QNetworkInterface::interfaceFromName(name).index()
\endcode
\snippet code/src_network_kernel_qnetworkinterface.cpp 0
\sa interfaceFromName(), interfaceNameFromIndex(), QNetworkDatagram::interfaceIndex()
*/
@ -858,9 +856,7 @@ QNetworkInterface QNetworkInterface::interfaceFromIndex(int index)
produce the same result as the following code, but will probably execute
faster.
\code
QNetworkInterface::interfaceFromIndex(index).name()
\endcode
\snippet code/src_network_kernel_qnetworkinterface.cpp 1
\sa interfaceFromIndex(), interfaceIndexFromName(), QNetworkDatagram::interfaceIndex()
*/

19
src/network/ssl/qsslpresharedkeyauthenticator.cpp
View File

@ -83,28 +83,13 @@ QSslPreSharedKeyAuthenticatorPrivate::QSslPreSharedKeyAuthenticatorPrivate()
completing the PSK handshake. The client application needs to connect a
slot to the QSslSocket::preSharedKeyAuthenticationRequired() signal:
\code
connect(socket, &QSslSocket::preSharedKeyAuthenticationRequired,
this, &AuthManager::handlePreSharedKeyAuthentication);
\endcode
\snippet code/src_network_ssl_qsslpresharedkeyauthenticator.cpp 0
The signal carries a QSslPreSharedKeyAuthenticator object containing the
identity hint the server sent to the client, and which must be filled with the
corresponding client identity and the derived key:
\code
void AuthManager::handlePreSharedKeyAuthentication(QSslPreSharedKeyAuthenticator *authenticator)
{
authenticator->setIdentity("My Qt App");
const QByteArray key = deriveKey(authenticator->identityHint(), passphrase);
authenticator->setPreSharedKey(key);
}
\endcode
\snippet code/src_network_ssl_qsslpresharedkeyauthenticator.cpp 1
\note PSK ciphersuites are supported only when using OpenSSL 1.0.1 (or
greater) as the SSL backend.

49
src/opengl/doc/snippets/code/src_opengl_qglbuffer.cpp Normal file
View File

@ -0,0 +1,49 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtOpenGL module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
QGLBuffer buffer1(QGLBuffer::IndexBuffer);
buffer1.create();
QGLBuffer buffer2 = buffer1;
//! [0]
//! [1]
QGLBuffer::release(QGLBuffer::VertexBuffer);
//! [1]

75
src/opengl/doc/snippets/code/src_opengl_qglfunctions.cpp Normal file
View File

@ -0,0 +1,75 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtOpenGL module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
class MyGLWidget : public QGLWidget, protected QGLFunctions
{
Q_OBJECT
public:
MyGLWidget(QWidget *parent = 0) : QGLWidget(parent) {}
protected:
void initializeGL();
void paintGL();
};
void MyGLWidget::initializeGL()
{
initializeGLFunctions();
}
//! [0]
//! [1]
void MyGLWidget::paintGL()
{
glActiveTexture(GL_TEXTURE1);
glBindTexture(GL_TEXTURE_2D, textureId);
...
}
//! [1]
//! [2]
QGLFunctions glFuncs(QGLContext::currentContext());
glFuncs.glActiveTexture(GL_TEXTURE1);
//! [2]
//! [3]
QGLFunctions funcs(QGLContext::currentContext());
bool npot = funcs.hasOpenGLFeature(QGLFunctions::NPOTTextures);
//! [3]

84
src/opengl/doc/snippets/code/src_opengl_qgraphicsshadereffect.cpp Normal file
View File

@ -0,0 +1,84 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the QtOpenGL module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/
//! [0]
static char const colorizeShaderCode[] =
"uniform lowp vec4 effectColor;\n"
"lowp vec4 customShader(lowp sampler2D imageTexture, highp vec2 textureCoords) {\n"
" vec4 src = texture2D(imageTexture, textureCoords);\n"
" float gray = dot(src.rgb, vec3(0.212671, 0.715160, 0.072169));\n"
" vec4 colorize = 1.0-((1.0-gray)*(1.0-effectColor));\n"
" return vec4(colorize.rgb, src.a);\n"
"}";
//! [0]
//! [1]
class ColorizeEffect : public QGraphicsShaderEffect
{
Q_OBJECT
public:
ColorizeEffect(QObject *parent = 0)
: QGraphicsShaderEffect(parent), color(Qt::black)
{
setPixelShaderFragment(colorizeShaderCode);
}
QColor effectColor() const { return color; }
void setEffectColor(const QColor& c)
{
color = c;
setUniformsDirty();
}
protected:
void setUniforms(QGLShaderProgram *program)
{
program->setUniformValue("effectColor", color);
}
private:
QColor color;
};
//! [1]
//! [2]
lowp vec4 customShader(lowp sampler2D imageTexture, highp vec2 textureCoords) {
return texture2D(imageTexture, textureCoords);
}
//! [2]

11
src/opengl/qglbuffer.cpp
View File

@ -60,12 +60,7 @@ QT_BEGIN_NAMESPACE
QGLBuffer objects can be copied around as a reference to the
underlying GL buffer object:
\code
QGLBuffer buffer1(QGLBuffer::IndexBuffer);
buffer1.create();
QGLBuffer buffer2 = buffer1;
\endcode
\snippet code/src_opengl_qglbuffer.cpp 0
QGLBuffer performs a shallow copy when objects are copied in this
manner, but does not implement copy-on-write semantics. The original
@ -474,9 +469,7 @@ void QGLBuffer::release()
been bound to the context but wants to make sure that it
is released.
\code
QGLBuffer::release(QGLBuffer::VertexBuffer);
\endcode
\snippet code/src_opengl_qglbuffer.cpp 1
*/
void QGLBuffer::release(QGLBuffer::Type type)
{

Some files were not shown because too many files have changed in this diff Show More