diff options
114 files changed, 3627 insertions, 1647 deletions
diff --git a/src/corelib/animation/qparallelanimationgroup.cpp b/src/corelib/animation/qparallelanimationgroup.cpp index e4dfc1bd6e..f3184d6e54 100644 --- a/src/corelib/animation/qparallelanimationgroup.cpp +++ b/src/corelib/animation/qparallelanimationgroup.cpp @@ -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. diff --git a/src/corelib/animation/qpropertyanimation.cpp b/src/corelib/animation/qpropertyanimation.cpp index 5ba2a1fa73..f616dc71f8 100644 --- a/src/corelib/animation/qpropertyanimation.cpp +++ b/src/corelib/animation/qpropertyanimation.cpp @@ -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 diff --git a/src/corelib/animation/qsequentialanimationgroup.cpp b/src/corelib/animation/qsequentialanimationgroup.cpp index f5f538337e..23725ae415 100644 --- a/src/corelib/animation/qsequentialanimationgroup.cpp +++ b/src/corelib/animation/qsequentialanimationgroup.cpp @@ -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. diff --git a/src/corelib/animation/qvariantanimation.cpp b/src/corelib/animation/qvariantanimation.cpp index 3c90d71c7d..8711ec8a31 100644 --- a/src/corelib/animation/qvariantanimation.cpp +++ b/src/corelib/animation/qvariantanimation.cpp @@ -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 */ diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp new file mode 100644 index 0000000000..3fc53bc58b --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qparallelanimationgroup.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp new file mode 100644 index 0000000000..a6dbd909d7 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qpropertyanimation.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp new file mode 100644 index 0000000000..1f1363f127 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qsequentialanimationgroup.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp b/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp new file mode 100644 index 0000000000..b462ff2d6a --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_animation_qvariantanimation.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp index 9d029e5d4d..c73e782b76 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp new file mode 100644 index 0000000000..7b0b357cff --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_global_qlogging.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp new file mode 100644 index 0000000000..5d64070b1b --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_global_qnumeric.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp new file mode 100644 index 0000000000..d9e927c55a --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_global_qoperatingsystemversion.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp b/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp new file mode 100644 index 0000000000..b03e656b64 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_global_qrandom.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp new file mode 100644 index 0000000000..4bbdc509ca --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_io_qdebug.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp new file mode 100644 index 0000000000..91c94eb762 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_io_qfileselector.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp new file mode 100644 index 0000000000..20ae52a251 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_io_qloggingcategory.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp index 127c7bd0d9..4e864b3dcd 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qtemporaryfile.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp index b2a2282085..79af776ce4 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp new file mode 100644 index 0000000000..da87bfd143 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_io_qurlquery.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp new file mode 100644 index 0000000000..eb291d7b18 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qdeadlinetimer.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp index eda52cfacd..56d1fa5a63 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qmetaobject.cpp @@ -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] } diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp index 6451f46b36..1e31a5292f 100644 --- a/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qobject.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_kernel_qtestsupport_core.cpp b/src/corelib/doc/snippets/code/src_corelib_kernel_qtestsupport_core.cpp new file mode 100644 index 0000000000..ed3e9bd0c0 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_kernel_qtestsupport_core.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp b/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp index c5874d83b8..3092e32f6f 100644 --- a/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_mimetype_qmimedatabase.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp new file mode 100644 index 0000000000..dbe38aa4b5 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborstream.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp new file mode 100644 index 0000000000..63f813cf69 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qcborvalue.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp new file mode 100644 index 0000000000..5caaa16727 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qdatastream.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp b/src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp new file mode 100644 index 0000000000..c4913b1740 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_serialization_qjsondocument.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp index 2081e4fdd0..52105bce0b 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qsemaphore.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp index bd7cdaa681..32fccbefbf 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp @@ -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] + } diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearraymatcher.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearraymatcher.cpp new file mode 100644 index 0000000000..63fc1f91e7 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearraymatcher.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp new file mode 100644 index 0000000000..6bc9604243 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcontiguouscache.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp index c7df6f6090..a3d2dd7f9e 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp index 4bdaa4d657..a19dc086ac 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qrect.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp index b5d8320bce..afdd9c3d25 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qregularexpression.cpp @@ -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] + } diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp new file mode 100644 index 0000000000..45e8b0a965 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qshareddata.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp new file mode 100644 index 0000000000..69061ce298 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qsharedpointer.cpp @@ -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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qstring.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qstring.cpp index 9b3e89e5c4..4e79d1e27a 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qstring.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qstring.cpp @@ -102,3 +102,21 @@ QString plain = "#include <QtCore>" QString html = plain.toHtmlEscaped(); // html == "#include <QtCore>" //! [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] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qstringview.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qstringview.cpp new file mode 100644 index 0000000000..5dc153372c --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qstringview.cpp @@ -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] diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index a369bbe490..5c1665fa00 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -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 */ diff --git a/src/corelib/global/qlogging.cpp b/src/corelib/global/qlogging.cpp index a9c5d17aad..396aee8696 100644 --- a/src/corelib/global/qlogging.cpp +++ b/src/corelib/global/qlogging.cpp @@ -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}". diff --git a/src/corelib/global/qnumeric.cpp b/src/corelib/global/qnumeric.cpp index c03b139c9f..fc2b052edf 100644 --- a/src/corelib/global/qnumeric.cpp +++ b/src/corelib/global/qnumeric.cpp @@ -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 diff --git a/src/corelib/global/qoperatingsystemversion.cpp b/src/corelib/global/qoperatingsystemversion.cpp index 2f8d339ca7..94dc261b41 100644 --- a/src/corelib/global/qoperatingsystemversion.cpp +++ b/src/corelib/global/qoperatingsystemversion.cpp @@ -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 diff --git a/src/corelib/global/qrandom.cpp b/src/corelib/global/qrandom.cpp index a7d4aa303a..23e5e499b2 100644 --- a/src/corelib/global/qrandom.cpp +++ b/src/corelib/global/qrandom.cpp @@ -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() */ diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp index 2e825d2373..4d56d1a179 100644 --- a/src/corelib/io/qdebug.cpp +++ b/src/corelib/io/qdebug.cpp @@ -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 diff --git a/src/corelib/io/qfileselector.cpp b/src/corelib/io/qfileselector.cpp index 0ba8b124f7..ce06c8e00b 100644 --- a/src/corelib/io/qfileselector.cpp +++ b/src/corelib/io/qfileselector.cpp @@ -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 diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp index aa84f56368..33253429a2 100644 --- a/src/corelib/io/qloggingcategory.cpp +++ b/src/corelib/io/qloggingcategory.cpp @@ -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 diff --git a/src/corelib/io/qtemporaryfile.cpp b/src/corelib/io/qtemporaryfile.cpp index 1983a22c65..7e3be9ef36 100644 --- a/src/corelib/io/qtemporaryfile.cpp +++ b/src/corelib/io/qtemporaryfile.cpp @@ -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() */ diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp index 15785b48e0..b324df53b2 100644 --- a/src/corelib/io/qurl.cpp +++ b/src/corelib/io/qurl.cpp @@ -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. diff --git a/src/corelib/io/qurlquery.cpp b/src/corelib/io/qurlquery.cpp index 231a26c211..97e7b8a4eb 100644 --- a/src/corelib/io/qurlquery.cpp +++ b/src/corelib/io/qurlquery.cpp @@ -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. diff --git a/src/corelib/kernel/qdeadlinetimer.cpp b/src/corelib/kernel/qdeadlinetimer.cpp index 66d0dce7e8..466056d513 100644 --- a/src/corelib/kernel/qdeadlinetimer.cpp +++ b/src/corelib/kernel/qdeadlinetimer.cpp @@ -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. diff --git a/src/corelib/kernel/qmetaobject.cpp b/src/corelib/kernel/qmetaobject.cpp index a6ee12ede1..ac911e287b 100644 --- a/src/corelib/kernel/qmetaobject.cpp +++ b/src/corelib/kernel/qmetaobject.cpp @@ -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 diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp index 3cb8c45b41..07208b7f40 100644 --- a/src/corelib/kernel/qobject.cpp +++ b/src/corelib/kernel/qobject.cpp @@ -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. diff --git a/src/corelib/kernel/qtestsupport_core.cpp b/src/corelib/kernel/qtestsupport_core.cpp index 240e5795db..d69551a227 100644 --- a/src/corelib/kernel/qtestsupport_core.cpp +++ b/src/corelib/kernel/qtestsupport_core.cpp @@ -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. diff --git a/src/corelib/mimetypes/qmimedatabase.cpp b/src/corelib/mimetypes/qmimedatabase.cpp index 10b5c8eafd..35ea579767 100644 --- a/src/corelib/mimetypes/qmimedatabase.cpp +++ b/src/corelib/mimetypes/qmimedatabase.cpp @@ -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 diff --git a/src/corelib/serialization/qcborstream.cpp b/src/corelib/serialization/qcborstream.cpp index aed286a11f..22286188b8 100644 --- a/src/corelib/serialization/qcborstream.cpp +++ b/src/corelib/serialization/qcborstream.cpp @@ -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. diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp index 81ea1ed3b2..5d97a6a06a 100644 --- a/src/corelib/serialization/qcborvalue.cpp +++ b/src/corelib/serialization/qcborvalue.cpp @@ -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 diff --git a/src/corelib/serialization/qdatastream.cpp b/src/corelib/serialization/qdatastream.cpp index c81da70e61..951f6c9736 100644 --- a/src/corelib/serialization/qdatastream.cpp +++ b/src/corelib/serialization/qdatastream.cpp @@ -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 diff --git a/src/corelib/serialization/qjsondocument.cpp b/src/corelib/serialization/qjsondocument.cpp index 5018f7c267..0cd86d3ded 100644 --- a/src/corelib/serialization/qjsondocument.cpp +++ b/src/corelib/serialization/qjsondocument.cpp @@ -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 */ /*! diff --git a/src/corelib/thread/qsemaphore.cpp b/src/corelib/thread/qsemaphore.cpp index bb578ff617..aa04fb10ff 100644 --- a/src/corelib/thread/qsemaphore.cpp +++ b/src/corelib/thread/qsemaphore.cpp @@ -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 */ diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp index b53a60b9bf..8f2ad8c012 100644 --- a/src/corelib/tools/qbytearray.cpp +++ b/src/corelib/tools/qbytearray.cpp @@ -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 diff --git a/src/corelib/tools/qbytearraymatcher.cpp b/src/corelib/tools/qbytearraymatcher.cpp index a54afc5a9d..72f0e0519d 100644 --- a/src/corelib/tools/qbytearraymatcher.cpp +++ b/src/corelib/tools/qbytearraymatcher.cpp @@ -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 */ diff --git a/src/corelib/tools/qcontiguouscache.cpp b/src/corelib/tools/qcontiguouscache.cpp index 2ded61c0be..64cbd7df4b 100644 --- a/src/corelib/tools/qcontiguouscache.cpp +++ b/src/corelib/tools/qcontiguouscache.cpp @@ -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() */ diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp index 8d2616865e..32e9a4269c 100644 --- a/src/corelib/tools/qhash.cpp +++ b/src/corelib/tools/qhash.cpp @@ -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 diff --git a/src/corelib/tools/qrect.cpp b/src/corelib/tools/qrect.cpp index ad1885e8ce..6e51deebea 100644 --- a/src/corelib/tools/qrect.cpp +++ b/src/corelib/tools/qrect.cpp @@ -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() */ diff --git a/src/corelib/tools/qregularexpression.cpp b/src/corelib/tools/qregularexpression.cpp index 1026d4ab28..fec5f620fc 100644 --- a/src/corelib/tools/qregularexpression.cpp +++ b/src/corelib/tools/qregularexpression.cpp @@ -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 diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp index f95d75c4a8..bc4291e20f 100644 --- a/src/corelib/tools/qshareddata.cpp +++ b/src/corelib/tools/qshareddata.cpp @@ -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 diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp index 2d5fd2a00e..e58d3ab6bc 100644 --- a/src/corelib/tools/qsharedpointer.cpp +++ b/src/corelib/tools/qsharedpointer.cpp @@ -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() */ diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp index b3ed62982e..5a2d6b228d 100644 --- a/src/corelib/tools/qstring.cpp +++ b/src/corelib/tools/qstring.cpp @@ -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 diff --git a/src/corelib/tools/qstringview.cpp b/src/corelib/tools/qstringview.cpp index ce8fdacafb..a7d9426fa6 100644 --- a/src/corelib/tools/qstringview.cpp +++ b/src/corelib/tools/qstringview.cpp @@ -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. diff --git a/src/gui/accessible/qaccessible.cpp b/src/gui/accessible/qaccessible.cpp index 6b48f573b2..a3f53e149b 100644 --- a/src/gui/accessible/qaccessible.cpp +++ b/src/gui/accessible/qaccessible.cpp @@ -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, diff --git a/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp b/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp index 98d40c94f9..2fd76d08c7 100644 --- a/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp +++ b/src/gui/doc/snippets/code/src_gui_accessible_qaccessible.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp b/src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp new file mode 100644 index 0000000000..b5cd00d5aa --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_math3d_qquaternion.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp new file mode 100644 index 0000000000..4a4a6fe16d --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_opengl_qopenglbuffer.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp new file mode 100644 index 0000000000..4ab84deb3e --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_opengl_qopengldebug.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp b/src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp new file mode 100644 index 0000000000..68a20dcb7c --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_opengl_qopenglfunctions.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp b/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp index b48e9e8610..b9a8d8d90e 100644 --- a/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp +++ b/src/gui/doc/snippets/code/src_gui_util_qdesktopservices.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp new file mode 100644 index 0000000000..77c5444df5 --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanfunctions.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp new file mode 100644 index 0000000000..50afe7c0ff --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkaninstance.cpp @@ -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] diff --git a/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp new file mode 100644 index 0000000000..65eca4a77f --- /dev/null +++ b/src/gui/doc/snippets/code/src_gui_vulkan_qvulkanwindow.cpp @@ -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] diff --git a/src/gui/math3d/qquaternion.cpp b/src/gui/math3d/qquaternion.cpp index fe1b0425a8..899ec12eb3 100644 --- a/src/gui/math3d/qquaternion.cpp +++ b/src/gui/math3d/qquaternion.cpp @@ -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 { diff --git a/src/gui/opengl/qopenglbuffer.cpp b/src/gui/opengl/qopenglbuffer.cpp index 000494244d..537097c09f 100644 --- a/src/gui/opengl/qopenglbuffer.cpp +++ b/src/gui/opengl/qopenglbuffer.cpp @@ -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) { diff --git a/src/gui/opengl/qopengldebug.cpp b/src/gui/opengl/qopengldebug.cpp index 7072db5af4..2e628a2bd5 100644 --- a/src/gui/opengl/qopengldebug.cpp +++ b/src/gui/opengl/qopengldebug.cpp @@ -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 diff --git a/src/gui/opengl/qopenglfunctions.cpp b/src/gui/opengl/qopenglfunctions.cpp index 4f48604a88..b4ff21f3fd 100644 --- a/src/gui/opengl/qopenglfunctions.cpp +++ b/src/gui/opengl/qopenglfunctions.cpp @@ -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 */ diff --git a/src/gui/util/qdesktopservices.cpp b/src/gui/util/qdesktopservices.cpp index de9d087c21..b6eac91478 100644 --- a/src/gui/util/qdesktopservices.cpp +++ b/src/gui/util/qdesktopservices.cpp @@ -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). */ diff --git a/src/gui/vulkan/qvulkanfunctions.cpp b/src/gui/vulkan/qvulkanfunctions.cpp index c5f9616d20..73dbeb9ab6 100644 --- a/src/gui/vulkan/qvulkanfunctions.cpp +++ b/src/gui/vulkan/qvulkanfunctions.cpp @@ -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 diff --git a/src/gui/vulkan/qvulkaninstance.cpp b/src/gui/vulkan/qvulkaninstance.cpp index 8236d9625a..000c2b8caa 100644 --- a/src/gui/vulkan/qvulkaninstance.cpp +++ b/src/gui/vulkan/qvulkaninstance.cpp @@ -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 diff --git a/src/gui/vulkan/qvulkanwindow.cpp b/src/gui/vulkan/qvulkanwindow.cpp index 2e65ab49c5..6d12377a60 100644 --- a/src/gui/vulkan/qvulkanwindow.cpp +++ b/src/gui/vulkan/qvulkanwindow.cpp @@ -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() */ diff --git a/src/network/bearer/qnetworksession.cpp b/src/network/bearer/qnetworksession.cpp index e5562e3a0b..471d322998 100644 --- a/src/network/bearer/qnetworksession.cpp +++ b/src/network/bearer/qnetworksession.cpp @@ -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 diff --git a/src/network/doc/snippets/code/src_network_bearer_qnetworksession.cpp b/src/network/doc/snippets/code/src_network_bearer_qnetworksession.cpp new file mode 100644 index 0000000000..b88b6d1768 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_bearer_qnetworksession.cpp @@ -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] diff --git a/src/network/doc/snippets/code/src_network_kernel_qnetworkdatagram.cpp b/src/network/doc/snippets/code/src_network_kernel_qnetworkdatagram.cpp new file mode 100644 index 0000000000..f81ca97681 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_kernel_qnetworkdatagram.cpp @@ -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] diff --git a/src/network/doc/snippets/code/src_network_kernel_qnetworkinterface.cpp b/src/network/doc/snippets/code/src_network_kernel_qnetworkinterface.cpp new file mode 100644 index 0000000000..fc7fd7814a --- /dev/null +++ b/src/network/doc/snippets/code/src_network_kernel_qnetworkinterface.cpp @@ -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] diff --git a/src/network/doc/snippets/code/src_network_ssl_qsslpresharedkeyauthenticator.cpp b/src/network/doc/snippets/code/src_network_ssl_qsslpresharedkeyauthenticator.cpp new file mode 100644 index 0000000000..22e60840a3 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_ssl_qsslpresharedkeyauthenticator.cpp @@ -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] diff --git a/src/network/kernel/qnetworkdatagram.cpp b/src/network/kernel/qnetworkdatagram.cpp index 50421fa7f5..c8c87d4549 100644 --- a/src/network/kernel/qnetworkdatagram.cpp +++ b/src/network/kernel/qnetworkdatagram.cpp @@ -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 */ diff --git a/src/network/kernel/qnetworkinterface.cpp b/src/network/kernel/qnetworkinterface.cpp index 75a26848a6..d43dba3e0c 100644 --- a/src/network/kernel/qnetworkinterface.cpp +++ b/src/network/kernel/qnetworkinterface.cpp @@ -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() */ diff --git a/src/network/ssl/qsslpresharedkeyauthenticator.cpp b/src/network/ssl/qsslpresharedkeyauthenticator.cpp index 8e1313493f..3bb2719026 100644 --- a/src/network/ssl/qsslpresharedkeyauthenticator.cpp +++ b/src/network/ssl/qsslpresharedkeyauthenticator.cpp @@ -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. diff --git a/src/opengl/doc/snippets/code/src_opengl_qglbuffer.cpp b/src/opengl/doc/snippets/code/src_opengl_qglbuffer.cpp new file mode 100644 index 0000000000..c9e49826ae --- /dev/null +++ b/src/opengl/doc/snippets/code/src_opengl_qglbuffer.cpp @@ -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] diff --git a/src/opengl/doc/snippets/code/src_opengl_qglfunctions.cpp b/src/opengl/doc/snippets/code/src_opengl_qglfunctions.cpp new file mode 100644 index 0000000000..673186dca9 --- /dev/null +++ b/src/opengl/doc/snippets/code/src_opengl_qglfunctions.cpp @@ -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] diff --git a/src/opengl/doc/snippets/code/src_opengl_qgraphicsshadereffect.cpp b/src/opengl/doc/snippets/code/src_opengl_qgraphicsshadereffect.cpp new file mode 100644 index 0000000000..d53b73e837 --- /dev/null +++ b/src/opengl/doc/snippets/code/src_opengl_qgraphicsshadereffect.cpp @@ -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] diff --git a/src/opengl/qglbuffer.cpp b/src/opengl/qglbuffer.cpp index 200ee2499e..bb9c2affbd 100644 --- a/src/opengl/qglbuffer.cpp +++ b/src/opengl/qglbuffer.cpp @@ -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) { diff --git a/src/opengl/qglfunctions.cpp b/src/opengl/qglfunctions.cpp index 07e1194342..7fe7102510 100644 --- a/src/opengl/qglfunctions.cpp +++ b/src/opengl/qglfunctions.cpp @@ -62,44 +62,18 @@ QT_BEGIN_NAMESPACE that need it. The recommended way to use QGLFunctions is by direct inheritance: - \code - class MyGLWidget : public QGLWidget, protected QGLFunctions - { - Q_OBJECT - public: - MyGLWidget(QWidget *parent = 0) : QGLWidget(parent) {} - - protected: - void initializeGL(); - void paintGL(); - }; - - void MyGLWidget::initializeGL() - { - initializeGLFunctions(); - } - \endcode + \snippet code/src_opengl_qglfunctions.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 MyGLWidget::paintGL() - { - glActiveTexture(GL_TEXTURE1); - glBindTexture(GL_TEXTURE_2D, textureId); - ... - } - \endcode + \snippet code/src_opengl_qglfunctions.cpp 1 QGLFunctions can also be used directly for ad-hoc invocation of OpenGL ES 2.0 functions on all platforms: - \code - QGLFunctions glFuncs(QGLContext::currentContext()); - glFuncs.glActiveTexture(GL_TEXTURE1); - \endcode + \snippet code/src_opengl_qglfunctions.cpp 2 QGLFunctions provides wrappers for all OpenGL ES 2.0 functions, except those like \c{glDrawArrays()}, \c{glViewport()}, and @@ -114,10 +88,7 @@ QT_BEGIN_NAMESPACE feature. For example, the following checks if non power of two textures are available: - \code - QGLFunctions funcs(QGLContext::currentContext()); - bool npot = funcs.hasOpenGLFeature(QGLFunctions::NPOTTextures); - \endcode + \snippet code/src_opengl_qglfunctions.cpp 3 \note This class has been deprecated in favor of QOpenGLFunctions. */ diff --git a/src/opengl/qgraphicsshadereffect.cpp b/src/opengl/qgraphicsshadereffect.cpp index cf3d307d71..97b83a6b3d 100644 --- a/src/opengl/qgraphicsshadereffect.cpp +++ b/src/opengl/qgraphicsshadereffect.cpp @@ -70,48 +70,12 @@ QT_BEGIN_NAMESPACE grayscale and then applies a colorize operation using the \c effectColor value: - \code - 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" - "}"; - \endcode + \snippet code/src_opengl_qgraphicsshadereffect.cpp 0 To use this shader code, it is necessary to define a subclass of QGraphicsShaderEffect as follows: - \code - 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; - }; - \endcode + \snippet code/src_opengl_qgraphicsshadereffect.cpp 1 The setUniforms() function is called when the effect is about to be used for drawing to give the subclass the opportunity to @@ -216,11 +180,7 @@ QByteArray QGraphicsShaderEffect::pixelShaderFragment() const shader program. The following is the default pixel shader fragment, which draws a pixmap with no effect applied: - \code - lowp vec4 customShader(lowp sampler2D imageTexture, highp vec2 textureCoords) { - return texture2D(imageTexture, textureCoords); - } - \endcode + \snippet code/src_opengl_qgraphicsshadereffect.cpp 2 \sa pixelShaderFragment(), setUniforms() */ diff --git a/src/plugins/doc/snippets/code/src_plugins_platforms_qnx_qqnxwindow.cpp b/src/plugins/doc/snippets/code/src_plugins_platforms_qnx_qqnxwindow.cpp new file mode 100644 index 0000000000..ce82533c3e --- /dev/null +++ b/src/plugins/doc/snippets/code/src_plugins_platforms_qnx_qqnxwindow.cpp @@ -0,0 +1,52 @@ +/*************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the plugins 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] + QQuickView *view = new QQuickView(parent); + view->create(); + QGuiApplication::platformNativeInterface()->setWindowProperty(view->handle(), "qnxWindowGroup", + group); +//! [0] + +//! [1] + QQuickView *view = new QQuickView(parent); + view->create(); + QGuiApplication::platformNativeInterface()->setWindowProperty(view->handle(), "qnxWindowGroup", + QVariant()); +//! [1] diff --git a/src/plugins/platforms/qnx/qqnxwindow.cpp b/src/plugins/platforms/qnx/qqnxwindow.cpp index 5d9eaaa3ea..2096bc789e 100644 --- a/src/plugins/platforms/qnx/qqnxwindow.cpp +++ b/src/plugins/platforms/qnx/qqnxwindow.cpp @@ -132,22 +132,12 @@ DECLARE_DEBUG_VAR(statistics) setWindowProperty function of the native interface to set the \e qnxWindowGroup property to the desired value, for example: - \code - QQuickView *view = new QQuickView(parent); - view->create(); - QGuiApplication::platformNativeInterface()->setWindowProperty(view->handle(), "qnxWindowGroup", - group); - \endcode + \snippet code/src_plugins_platforms_qnx_qqnxwindow.cpp 0 To leave the current window group, one passes a null value for the property value, for example: - \code - QQuickView *view = new QQuickView(parent); - view->create(); - QGuiApplication::platformNativeInterface()->setWindowProperty(view->handle(), "qnxWindowGroup", - QVariant()); - \endcode + \snippet code/src_plugins_platforms_qnx_qqnxwindow.cpp 1 \section1 Window Id diff --git a/src/widgets/dialogs/qfiledialog.cpp b/src/widgets/dialogs/qfiledialog.cpp index 870a833b34..282540dcd9 100644 --- a/src/widgets/dialogs/qfiledialog.cpp +++ b/src/widgets/dialogs/qfiledialog.cpp @@ -2109,9 +2109,7 @@ QString QFileDialog::labelText(DialogLabel label) const strings. If you want multiple filters, separate them with ';;', for example: - \code - "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" - \endcode + \snippet code/src_gui_dialogs_qfiledialog.cpp 14 The \a options argument holds various options about how to run the dialog, see the QFileDialog::Option enum for more information on the flags you can @@ -2224,9 +2222,7 @@ QUrl QFileDialog::getOpenFileUrl(QWidget *parent, \a selectedFilter and \a filter may be empty strings. If you need multiple filters, separate them with ';;', for instance: - \code - "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" - \endcode + \snippet code/src_gui_dialogs_qfiledialog.cpp 14 The dialog's caption is set to \a caption. If \a caption is not specified then a default caption will be used. @@ -2340,9 +2336,7 @@ QList<QUrl> QFileDialog::getOpenFileUrls(QWidget *parent, parameters \a dir, \a selectedFilter, and \a filter may be empty strings. Multiple filters are separated with ';;'. For instance: - \code - "Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" - \endcode + \snippet code/src_gui_dialogs_qfiledialog.cpp 14 The \a options argument holds various options about how to run the dialog, see the QFileDialog::Option enum for more information on the flags you can diff --git a/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp b/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp index 58f0ae560f..06cca37111 100644 --- a/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp +++ b/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp @@ -140,3 +140,7 @@ QFileDialog dialog(this); dialog.setMimeTypeFilters(mimeTypeFilters); dialog.exec(); //! [13] + +//! [14] +"Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" +//! [14] diff --git a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp index 8d8c63db9e..ebca9d5368 100644 --- a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp +++ b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp @@ -271,3 +271,18 @@ QRect deviceRect = xform.mapRect(rect).toAlignedRect(); view->viewport()->scroll(dx, dy, deviceRect); //! [19] +//! [20] +item->setTransform(QTransform().rotate(angle), true); +//! [20] + +//! [21] +setTransform(QTransform::fromScale(sx, sy), true); +//! [21] + +//! [22] +setTransform(QTransform().shear(sh, sv), true); +//! [22] + +//! [23] +setTransform(QTransform::fromTranslate(dx, dy), true); +//! [23] diff --git a/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp b/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp index eadf753ded..a2ac780a82 100644 --- a/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp +++ b/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp @@ -84,3 +84,51 @@ formLayout->setFieldGrowthPolicy(QFormLayout::FieldsStayAtSizeHint); formLayout->setFormAlignment(Qt::AlignHCenter | Qt::AlignTop); formLayout->setLabelAlignment(Qt::AlignLeft); //! [2] + +//! [3] +QFormLayout *flay = ...; +QPointer<QLineEdit> le = new QLineEdit; +flay->insertRow(2, "User:", le); +// later: +flay->removeRow(2); // le == nullptr at this point +//! [3] + +//! [4] +QFormLayout *flay = ...; +QPointer<QLineEdit> le = new QLineEdit; +flay->insertRow(2, "User:", le); +// later: +flay->removeRow(le); // le == nullptr at this point +//! [4] + +//! [5] +QFormLayout *flay = ...; +QPointer<QVBoxLayout> vbl = new QVBoxLayout; +flay->insertRow(2, "User:", vbl); +// later: +flay->removeRow(layout); // vbl == nullptr at this point +//! [5] + +//! [6] +QFormLayout *flay = ...; +QPointer<QLineEdit> le = new QLineEdit; +flay->insertRow(2, "User:", le); +// later: +QFormLayout::TakeRowResult result = flay->takeRow(2); +//! [6] + +//! [7] +QFormLayout *flay = ...; +QPointer<QLineEdit> le = new QLineEdit; +flay->insertRow(2, "User:", le); +// later: +QFormLayout::TakeRowResult result = flay->takeRow(widget); +//! [7] + +//! [8] +QFormLayout *flay = ...; +QPointer<QVBoxLayout> vbl = new QVBoxLayout; +flay->insertRow(2, "User:", vbl); +// later: +QFormLayout::TakeRowResult result = flay->takeRow(widget); +//! [8] diff --git a/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp b/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp new file mode 100644 index 0000000000..2b3d825266 --- /dev/null +++ b/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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] + QWidget *w = ...; + QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture); +//! [0] + +//! [1] + QWidget *w = ...; + QScroller *scroller = QScroller::scroller(w); + scroller->scrollTo(QPointF(100, 100)); +//! [1] diff --git a/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp b/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp new file mode 100644 index 0000000000..8ebaaf3991 --- /dev/null +++ b/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** 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 MainWindow::createMenus() + { + fileMenu = menuBar()->addMenu(tr("&File")); + fileMenu->addAction(newAct); + fileMenu->addAction(openAct); + fileMenu->addAction(saveAct); +//! [0] + +//! [1] + void MainWindow::createToolBars() + { + fileToolBar = addToolBar(tr("File")); + fileToolBar->addAction(newAct); +//! [1] + +//! [2] + resizeDocks({blueWidget, yellowWidget}, {20 , 40}, Qt::Horizontal); +//! [2] diff --git a/src/widgets/graphicsview/qgraphicsitem.cpp b/src/widgets/graphicsview/qgraphicsitem.cpp index a32f1388bf..e81eab4c46 100644 --- a/src/widgets/graphicsview/qgraphicsitem.cpp +++ b/src/widgets/graphicsview/qgraphicsitem.cpp @@ -4666,9 +4666,7 @@ void QGraphicsItem::resetTransform() Use - \code - item->setTransform(QTransform().rotate(angle), true); - \endcode + \snippet code/src_gui_graphicsview_qgraphicsitem.cpp 20 instead. @@ -4689,9 +4687,7 @@ void QGraphicsItem::resetTransform() Use - \code - setTransform(QTransform::fromScale(sx, sy), true); - \endcode + \snippet code/src_gui_graphicsview_qgraphicsitem.cpp 21 instead. @@ -4712,9 +4708,7 @@ void QGraphicsItem::resetTransform() Use - \code - setTransform(QTransform().shear(sh, sv), true); - \endcode + \snippet code/src_gui_graphicsview_qgraphicsitem.cpp 22 instead. @@ -4730,9 +4724,7 @@ void QGraphicsItem::resetTransform() Use setPos() or setTransformOriginPoint() instead. For identical behavior, use - \code - setTransform(QTransform::fromTranslate(dx, dy), true); - \endcode + \snippet code/src_gui_graphicsview_qgraphicsitem.cpp 23 Translates the current item transformation by (\a dx, \a dy). diff --git a/src/widgets/kernel/qformlayout.cpp b/src/widgets/kernel/qformlayout.cpp index 595ff3eb6e..66e8858e21 100644 --- a/src/widgets/kernel/qformlayout.cpp +++ b/src/widgets/kernel/qformlayout.cpp @@ -1435,13 +1435,7 @@ static void clearAndDestroyQLayoutItem(QLayoutItem *item) up one row and the freed vertical space is redistributed amongst the remaining rows. You can use this function to undo a previous addRow() or insertRow(): - \code - QFormLayout *flay = ...; - QPointer<QLineEdit> le = new QLineEdit; - flay->insertRow(2, "User:", le); - // later: - flay->removeRow(2); // le == nullptr at this point - \endcode + \snippet code/src_gui_kernel_qformlayout.cpp 3 If you want to remove the row from the layout without deleting the widgets, use takeRow() instead. @@ -1467,13 +1461,7 @@ void QFormLayout::removeRow(int row) up one row and the freed vertical space is redistributed amongst the remaining rows. You can use this function to undo a previous addRow() or insertRow(): - \code - QFormLayout *flay = ...; - QPointer<QLineEdit> le = new QLineEdit; - flay->insertRow(2, "User:", le); - // later: - flay->removeRow(le); // le == nullptr at this point - \endcode + \snippet code/src_gui_kernel_qformlayout.cpp 4 If you want to remove the row from the layout without deleting the widgets, use takeRow() instead. @@ -1499,13 +1487,7 @@ void QFormLayout::removeRow(QWidget *widget) up one row and the freed vertical space is redistributed amongst the remaining rows. You can use this function to undo a previous addRow() or insertRow(): - \code - QFormLayout *flay = ...; - QPointer<QVBoxLayout> vbl = new QVBoxLayout; - flay->insertRow(2, "User:", vbl); - // later: - flay->removeRow(layout); // vbl == nullptr at this point - \endcode + \snippet code/src_gui_kernel_qformlayout.cpp 5 If you want to remove the row from the form layout without deleting the inserted layout, use takeRow() instead. @@ -1532,13 +1514,7 @@ void QFormLayout::removeRow(QLayout *layout) up one row and the freed vertical space is redistributed amongst the remaining rows. You can use this function to undo a previous addRow() or insertRow(): - \code - QFormLayout *flay = ...; - QPointer<QLineEdit> le = new QLineEdit; - flay->insertRow(2, "User:", le); - // later: - QFormLayout::TakeRowResult result = flay->takeRow(2); - \endcode + \snippet code/src_gui_kernel_qformlayout.cpp 6 If you want to remove the row from the layout and delete the widgets, use removeRow() instead. @@ -1583,13 +1559,7 @@ QFormLayout::TakeRowResult QFormLayout::takeRow(int row) After this call, rowCount() is decremented by one. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows. - \code - QFormLayout *flay = ...; - QPointer<QLineEdit> le = new QLineEdit; - flay->insertRow(2, "User:", le); - // later: - QFormLayout::TakeRowResult result = flay->takeRow(widget); - \endcode + \snippet code/src_gui_kernel_qformlayout.cpp 7 If you want to remove the row from the layout and delete the widgets, use removeRow() instead. @@ -1628,13 +1598,7 @@ QFormLayout::TakeRowResult QFormLayout::takeRow(QWidget *widget) After this call, rowCount() is decremented by one. All following rows are shifted up one row and the freed vertical space is redistributed amongst the remaining rows. - \code - QFormLayout *flay = ...; - QPointer<QVBoxLayout> vbl = new QVBoxLayout; - flay->insertRow(2, "User:", vbl); - // later: - QFormLayout::TakeRowResult result = flay->takeRow(widget); - \endcode + \snippet code/src_gui_kernel_qformlayout.cpp 8 If you want to remove the row from the form layout and delete the inserted layout, use removeRow() instead. diff --git a/src/widgets/util/qscroller.cpp b/src/widgets/util/qscroller.cpp index 28504f5631..386fc0d103 100644 --- a/src/widgets/util/qscroller.cpp +++ b/src/widgets/util/qscroller.cpp @@ -249,18 +249,11 @@ private: scrolling speed and takes care of updates. QScroller can be triggered by a flick gesture - \code - QWidget *w = ...; - QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture); - \endcode + \snippet code/src_widgets_util_qscroller.cpp 0 or directly like this: - \code - QWidget *w = ...; - QScroller *scroller = QScroller::scroller(w); - scroller->scrollTo(QPointF(100, 100)); - \endcode + \snippet code/src_widgets_util_qscroller.cpp 1 The scrolled QObjects receive a QScrollPrepareEvent whenever the scroller needs to update its geometry information and a QScrollEvent whenever the content of the object should diff --git a/src/widgets/widgets/qmainwindow.cpp b/src/widgets/widgets/qmainwindow.cpp index aca38884a7..411b482c11 100644 --- a/src/widgets/widgets/qmainwindow.cpp +++ b/src/widgets/widgets/qmainwindow.cpp @@ -249,14 +249,7 @@ void QMainWindowPrivate::init() An example of how to create menus follows: - \code - void MainWindow::createMenus() - { - fileMenu = menuBar()->addMenu(tr("&File")); - fileMenu->addAction(newAct); - fileMenu->addAction(openAct); - fileMenu->addAction(saveAct); - \endcode + \snippet code/src_widgets_widgets_qmainwindow.cpp 0 The \c createPopupMenu() function creates popup menus when the main window receives context menu events. The default @@ -283,12 +276,7 @@ void QMainWindowPrivate::init() An example of toolbar creation follows: - \code - void MainWindow::createToolBars() - { - fileToolBar = addToolBar(tr("File")); - fileToolBar->addAction(newAct); - \endcode + \snippet code/src_widgets_widgets_qmainwindow.cpp 1 \section2 Creating Dock Widgets @@ -1227,9 +1215,8 @@ Qt::DockWidgetArea QMainWindow::dockWidgetArea(QDockWidget *dockwidget) const to the relative weight of the sizes. Example: - \code - resizeDocks({blueWidget, yellowWidget}, {20 , 40}, Qt::Horizontal); - \endcode + \snippet code/src_widgets_widgets_qmainwindow.cpp 2 + If the blue and the yellow widget are nested on the same level they will be resized such that the yellowWidget is twice as big as the blueWidget |