diff options
Diffstat (limited to 'src/corelib/doc')
24 files changed, 377 insertions, 810 deletions
diff --git a/src/corelib/doc/qtcore.qdocconf b/src/corelib/doc/qtcore.qdocconf index c9c8f1da54..5a14ba9088 100644 --- a/src/corelib/doc/qtcore.qdocconf +++ b/src/corelib/doc/qtcore.qdocconf @@ -2,10 +2,9 @@ include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) project = QtCore description = Qt Core Reference Documentation -url = http://qt-project.org/doc/qt-$QT_VER version = $QT_VERSION -examplesinstallpath = core +examplesinstallpath = corelib qhp.projects = QtCore @@ -36,10 +35,7 @@ sourcedirs += .. exampledirs += \ ../ \ snippets \ - ../../../examples/threads/ \ - ../../../examples/tools/ \ - ../../../examples/ipc/ \ - ../../../examples/json/ \ + ../../../examples/corelib \ ../../../examples/network/dnslookup imagedirs += images diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro b/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro deleted file mode 100644 index dc75c1d9d7..0000000000 --- a/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro +++ /dev/null @@ -1,61 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** 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 Digia Plc and its Subsidiary(-ies) 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$ -** -****************************************************************************/ - -#! [3] -CONFIG += release -#! [3] - -#! [4] -QTPLUGIN.platforms = qminimal -#! [4] - -#! [5] -QTPLUGIN += qjpeg \ - qgif \ - qkrcodecs -#! [5] - -#! [6] -QTPLUGIN.platforms = - -#! [6] - -#! [7] -CONFIG -= import_plugins -#! [7] diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc b/src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc deleted file mode 100644 index 46b8245ba6..0000000000 --- a/src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc +++ /dev/null @@ -1,43 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** 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 Digia Plc and its Subsidiary(-ies) 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$ -** -****************************************************************************/ - -//! [6] -{ "Keys": [ "mystyleplugin" ] } -//! [6] 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 b907c9acb1..d804514584 100644 --- a/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_global_qglobal.cpp @@ -136,9 +136,9 @@ int roundedValueB = qRound(valueB); qreal valueA = 42949672960.3; qreal valueB = 42949672960.7; -int roundedValueA = qRound(valueA); +qint64 roundedValueA = qRound64(valueA); // roundedValueA = 42949672960 -int roundedValueB = qRound(valueB); +qint64 roundedValueB = qRound64(valueB); // roundedValueB = 42949672961 //! [12] @@ -305,7 +305,7 @@ void load(const QString &fileName) { QFile file(fileName); if (!file.exists()) - qCritical("File '%s' does not exist!", qPrintable(fileName)); + qCritical("File '%s' does not exist!", qUtf8Printable(fileName)); } //! [28] @@ -424,7 +424,7 @@ void TheClass::addLabels() //! [37] -qWarning("%s: %s", qPrintable(key), qPrintable(value)); +qWarning("%s: %s", qUtf8Printable(key), qUtf8Printable(value)); //! [37] diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp new file mode 100644 index 0000000000..bba3703325 --- /dev/null +++ b/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Ivan Komissarov +** Contact: http://www.qt-project.org/legal +** +** This file is part of the QtCore module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL21$ +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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 2.1 or version 3 as published by the Free +** Software Foundation and appearing in the file LICENSE.LGPLv21 and +** LICENSE.LGPLv3 included in the packaging of this file. Please review the +** following information to ensure the GNU Lesser General Public License +** requirements will be met: https://www.gnu.org/licenses/lgpl.html and +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QStorageInfo storage(qApp->applicationDirPath()); + if (storage.isValid() && storage.isReady()) { + // ... + } +//! [0] + +//! [1] + foreach (const QStorageInfo &storage, QStorageInfo::mountedVolumes()) { + if (storage.isValid() && storage.isReady()) { + if (!storage.isReadOnly()) { + // ... + } + } + } +//! [1] + +//! [2] + QStorageInfo storage = QStorageInfo::root(); + + qDebug() << storage.rootPath(); + if (storage.isReadOnly()) + qDebug() << "isReadOnly:" << storage.isReadOnly(); + + qDebug() << "name:" << storage.name(); + qDebug() << "fileSystemType:" << storage.fileSystemType(); + qDebug() << "size:" << storage.bytesTotal()/1000/1000 << "MB"; + qDebug() << "availableSize:" << storage.bytesAvailable()/1000/1000 << "MB"; +//! [2] 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 9210d2737f..97be131203 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp @@ -354,10 +354,10 @@ text.toBase64(); // returns "UXQgaXMgZ3JlYXQh" //! [39bis] QByteArray text("<p>Hello?</p>"); -text.toBase64(QByteArray::Base64 | QByteArray::OmitTrailingEquals); // returns "PHA+SGVsbG8/PC9wPg" -text.toBase64(QByteArray::Base64); // returns "PHA+SGVsbG8/PC9wPg==" -text.toBase64(QByteArray::Base64Url); // returns "PHA-SGVsbG8_PC9wPg==" -text.toBase64(QByteArray::Base64Url | QByteArray::OmitTrailingEquals); // returns "PHA-SGVsbG8_PC9wPg" +text.toBase64(QByteArray::Base64Encoding | QByteArray::OmitTrailingEquals); // returns "PHA+SGVsbG8/PC9wPg" +text.toBase64(QByteArray::Base64Encoding); // returns "PHA+SGVsbG8/PC9wPg==" +text.toBase64(QByteArray::Base64UrlEncoding); // returns "PHA-SGVsbG8_PC9wPg==" +text.toBase64(QByteArray::Base64UrlEncoding | QByteArray::OmitTrailingEquals); // returns "PHA-SGVsbG8_PC9wPg" //! [39bis] diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp index 67d5f41b38..6d6d7fe2ed 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineoption.cpp @@ -39,6 +39,7 @@ ****************************************************************************/ #include <QCommandLineOption> +#include <QCommandLineParser> int main() { @@ -48,4 +49,14 @@ QCommandLineOption verboseOption("verbose", "Verbose mode. Prints out more infor QCommandLineOption outputOption(QStringList() << "o" << "output", "Write generated data into <file>.", "file"); //! [0] +//! [cxx11-init] +QCommandLineParser parser; +parser.addOption({"verbose", "Verbose mode. Prints out more information."}); +//! [cxx11-init] + +//! [cxx11-init-list] +QCommandLineParser parser; +parser.addOption({{"o", "output"}, "Write generated data into <file>.", "file"}); +//! [cxx11-init-list] + } diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp index 257a138d0d..26bc43f194 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qcommandlineparser_main.cpp @@ -82,3 +82,20 @@ int main(int argc, char *argv[]) } //! [0] + +void f() { +//! [cxx11] + parser.addOptions({ + // A boolean option with a single name (-p) + {"p", + QCoreApplication::translate("main", "Show progress during copy")}, + // A boolean option with multiple names (-f, --force) + {{"f", "force"}, + QCoreApplication::translate("main", "Overwrite existing files.")}, + // An option with a value + {{"t", "target-directory"}, + QCoreApplication::translate("main", "Copy all source files into <directory>."), + QCoreApplication::translate("main", "directory")}, + }); +//! [cxx11] +} 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 8c21083976..aa0473964c 100644 --- a/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_tools_qhash.cpp @@ -297,3 +297,13 @@ while (i != hash.end() && i.key() == "plenty") { ++i; } //! [26] + +//! [qhashbits] +inline uint qHash(const std::vector<int> &key, uint seed = 0) +{ + if (key.empty()) + return seed; + else + return qHashBits(&key.front(), key.size() * sizeof(int), seed); +} +//! [qhashbits] diff --git a/src/corelib/doc/snippets/plugins/extrafiltersplugin.h b/src/corelib/doc/snippets/plugins/extrafiltersplugin.h deleted file mode 100644 index 7add7abb53..0000000000 --- a/src/corelib/doc/snippets/plugins/extrafiltersplugin.h +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** 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 Digia Plc and its Subsidiary(-ies) 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$ -** -****************************************************************************/ - -#ifndef EXTRAFILTERSPLUGIN_H -#define EXTRAFILTERSPLUGIN_H - -//! [0] -#include <QObject> -#include <QtPlugin> -#include <QStringList> -#include <QImage> - -#include <plugandpaint/interfaces.h> - -class ExtraFiltersPlugin : public QObject, public FilterInterface -{ - Q_OBJECT - Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.PlugAndPaint.FilterInterface" FILE "extrafilters.json") - Q_INTERFACES(FilterInterface) - -public: - QStringList filters() const; - QImage filterImage(const QString &filter, const QImage &image, - QWidget *parent); -}; -//! [0] - -#endif diff --git a/src/corelib/doc/snippets/plugins/interfaces.h b/src/corelib/doc/snippets/plugins/interfaces.h deleted file mode 100644 index b2261a1eb2..0000000000 --- a/src/corelib/doc/snippets/plugins/interfaces.h +++ /dev/null @@ -1,114 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** 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 Digia Plc and its Subsidiary(-ies) 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$ -** -****************************************************************************/ - -#ifndef INTERFACES_H -#define INTERFACES_H - -#include <QtPlugin> - -QT_BEGIN_NAMESPACE -class QImage; -class QPainter; -class QWidget; -class QPainterPath; -class QPoint; -class QRect; -class QString; -class QStringList; -QT_END_NAMESPACE - -//! [0] -class BrushInterface -{ -public: - virtual ~BrushInterface() {} - - virtual QStringList brushes() const = 0; - virtual QRect mousePress(const QString &brush, QPainter &painter, - const QPoint &pos) = 0; - virtual QRect mouseMove(const QString &brush, QPainter &painter, - const QPoint &oldPos, const QPoint &newPos) = 0; - virtual QRect mouseRelease(const QString &brush, QPainter &painter, - const QPoint &pos) = 0; -}; -//! [0] - -//! [1] -class ShapeInterface -{ -public: - virtual ~ShapeInterface() {} - - virtual QStringList shapes() const = 0; - virtual QPainterPath generateShape(const QString &shape, - QWidget *parent) = 0; -}; -//! [1] - -//! [2] -class FilterInterface -{ -public: - virtual ~FilterInterface() {} - - virtual QStringList filters() const = 0; - virtual QImage filterImage(const QString &filter, const QImage &image, - QWidget *parent) = 0; -}; -//! [2] - -QT_BEGIN_NAMESPACE -//! [3] //! [4] -#define BrushInterface_iid "org.qt-project.Qt.Examples.PlugAndPaint.BrushInterface" - -Q_DECLARE_INTERFACE(BrushInterface, BrushInterface_iid) -//! [3] - -#define ShapeInterface_iid "org.qt-project.Qt.Examples.PlugAndPaint.ShapeInterface" - -Q_DECLARE_INTERFACE(ShapeInterface, ShapeInterface_iid) -//! [5] -#define FilterInterface_iid "org.qt-project.Qt.Examples.PlugAndPaint.FilterInterface" - -Q_DECLARE_INTERFACE(FilterInterface, FilterInterface_iid) -//! [4] //! [5] -QT_END_NAMESPACE - -#endif diff --git a/src/corelib/doc/snippets/qbytearraylist/main.cpp b/src/corelib/doc/snippets/qbytearraylist/main.cpp new file mode 100644 index 0000000000..be462dea60 --- /dev/null +++ b/src/corelib/doc/snippets/qbytearraylist/main.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2014 by Southwest Research Institute (R) +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +#include <QByteArrayList> + +int main(int, char **) +{ + QByteArray ba1, ba2, ba3; +//! [0] + QByteArrayList longerList = (QByteArrayList() << ba1 << ba2 << ba3); +//! [0] +} diff --git a/src/corelib/doc/snippets/qbytearraylist/qbytearraylist.pro b/src/corelib/doc/snippets/qbytearraylist/qbytearraylist.pro new file mode 100644 index 0000000000..87397b491d --- /dev/null +++ b/src/corelib/doc/snippets/qbytearraylist/qbytearraylist.pro @@ -0,0 +1,2 @@ +QT = core +SOURCES = main.cpp diff --git a/src/corelib/doc/snippets/qloggingcategory/main.cpp b/src/corelib/doc/snippets/qloggingcategory/main.cpp index 628243dbdd..3c6424921e 100644 --- a/src/corelib/doc/snippets/qloggingcategory/main.cpp +++ b/src/corelib/doc/snippets/qloggingcategory/main.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the examples of the Qt Toolkit. @@ -43,12 +43,15 @@ //![1] // in a header -Q_DECLARE_LOGGING_CATEGORY(QT_DRIVER_USB) +Q_DECLARE_LOGGING_CATEGORY(driverUsb) // in one source file -Q_LOGGING_CATEGORY(QT_DRIVER_USB, "qt.driver.usb") +Q_LOGGING_CATEGORY(driverUsb, "driver.usb") //![1] +//![5] +Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg) +//![5] // Completely made up example, inspired by en.wikipedia.org/wiki/USB :) struct UsbEntry { @@ -76,8 +79,8 @@ QLoggingCategory::CategoryFilter oldCategoryFilter; void myCategoryFilter(QLoggingCategory *category) { - // configure qt.driver.usb category here, otherwise forward to to default filter. - if (qstrcmp(category->categoryName(), "qt.driver.usb") == 0) + // configure driver.usb category here, otherwise forward to to default filter. + if (qstrcmp(category->categoryName(), "driver.usb") == 0) category->setEnabled(QtDebugMsg, true); else oldCategoryFilter(category); @@ -89,7 +92,7 @@ int main(int argc, char *argv[]) QCoreApplication a(argc, argv); //![2] - QLoggingCategory::setFilterRules(QStringLiteral("qt.driver.usb.debug=true")); + QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true")); //![2] //![22] @@ -103,48 +106,48 @@ oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter); //![3] //![4] - // usbEntries() will only be called if QT_DRIVER_USB category is enabled - qCDebug(QT_DRIVER_USB) << "devices: " << usbEntries(); + // usbEntries() will only be called if driverUsb category is enabled + qCDebug(driverUsb) << "devices: " << usbEntries(); //![4] { //![10] - QLoggingCategory category("qt.driver.usb"); + QLoggingCategory category("driver.usb"); qCDebug(category) << "a debug message"; //![10] } { //![11] - QLoggingCategory category("qt.driver.usb"); + QLoggingCategory category("driver.usb"); qCWarning(category) << "a warning message"; //![11] } { //![12] - QLoggingCategory category("qt.driver.usb"); + QLoggingCategory category("driver.usb"); qCCritical(category) << "a critical message"; //![12] } { //![13] - QLoggingCategory category("qt.driver.usb"); + QLoggingCategory category("driver.usb"); qCDebug(category, "a debug message logged into category %s", category.categoryName()); //![13] } { //![14] - QLoggingCategory category("qt.driver.usb"); + QLoggingCategory category("driver.usb"); qCWarning(category, "a warning message logged into category %s", category.categoryName()); //![14] } { //![15] - QLoggingCategory category("qt.driver.usb"); + QLoggingCategory category("driver.usb"); qCCritical(category, "a critical message logged into category %s", category.categoryName()); //![15] } diff --git a/src/corelib/doc/snippets/qprocess-environment/main.cpp b/src/corelib/doc/snippets/qprocess-environment/main.cpp index d858746889..2e078eea6d 100644 --- a/src/corelib/doc/snippets/qprocess-environment/main.cpp +++ b/src/corelib/doc/snippets/qprocess-environment/main.cpp @@ -47,7 +47,6 @@ void startProcess() QProcess process; QStringList env = QProcess::systemEnvironment(); env << "TMPDIR=C:\\MyApp\\temp"; // Add an environment variable -env.replaceInStrings(QRegExp("^PATH=(.*)", Qt::CaseInsensitive), "PATH=\\1;C:\\Bin"); process.setEnvironment(env); process.start("myapp"); //! [0] @@ -58,7 +57,6 @@ process.start("myapp"); QProcess process; QProcessEnvironment env = QProcessEnvironment::systemEnvironment(); env.insert("TMPDIR", "C:\\MyApp\\temp"); // Add an environment variable -env.insert("PATH", env.value("Path") + ";C:\\Bin"); process.setProcessEnvironment(env); process.start("myapp"); //! [1] diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp b/src/corelib/doc/snippets/qversionnumber/main.cpp index b86f0bbf68..ba72a52816 100644 --- a/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp +++ b/src/corelib/doc/snippets/qversionnumber/main.cpp @@ -1,6 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Keith Gardner <kreios4004@gmail.com> ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -38,30 +39,71 @@ ** ****************************************************************************/ -//! [0] -class MyStylePlugin : public QStylePlugin +#include <QVersionNumber> + +class Object { - Q_OBJECT - Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QStyleFactoryInterface" FILE "mystyleplugin.json") public: - QStyle *create(const QString &key); + static void genericExample(); + static void equalityExample(); + static void isPrefixOf(); + static void parse(); + static void equivalent(); }; -//! [0] +void Object::genericExample() +{ + //! [0] + QVersionNumber version(1, 2, 3); // 1.2.3 + //! [0] +} -//! [1] -#include "mystyleplugin.h" +void Object::equalityExample() +{ + //! [1] + QVersionNumber v1(1, 2); + QVersionNumber v2(1, 2, 0); + int compare = QVersionNumber::compare(v1, v2); // compare == -1 + //! [1] +} -QStyle *MyStylePlugin::create(const QString &key) +void Object::isPrefixOf() { - if (key.toLower() == "mystyle") - return new MyStyle; - return 0; + //! [2] + QVersionNumber v1(5, 3); + QVersionNumber v2(5, 3, 1); + bool value = v1.isPrefixOf(v2); // true + //! [2] } -//! [1] +void QObject::parse() +{ + //! [3] + QString string("5.4.0-alpha"); + int suffixIndex; + QVersionNumber version = QVersionNumber::fromString(string, &suffixIndex); + // version is 5.4.0 + // suffixIndex is 5 + //! [3] +} +void Object::equivalent() +{ + //! [4] + QVersionNumber v1(5, 4); + QVersionNumber v2(5, 4, 0); + bool equivalent = v1.normalized() == v2.normalized(); + bool equal = v1 == v2; + // equivalent is true + // equal is false + //! [4] +} -//! [2] -QApplication::setStyle(QStyleFactory::create("MyStyle")); -//! [2] +int main() +{ + Object::genericExample(); + Object::equalityExample(); + Object::isPrefixOf(); + Object::parse(); + Object::equivalent(); +} diff --git a/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp b/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp index 91cd3de9d2..357269bac0 100644 --- a/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp +++ b/src/corelib/doc/snippets/signalsandslots/signalsandslots.cpp @@ -38,8 +38,6 @@ ** ****************************************************************************/ -#include <QAbstractButton> - #include "signalsandslots.h" //! [0] @@ -66,19 +64,4 @@ int main() //! [3] //! [4] b.setValue(48); // a.value() == 12, b.value() == 48 //! [4] - - - QWidget *widget = reinterpret_cast<QWidget *>(new QObject(0)); -//! [5] - if (widget->inherits("QAbstractButton")) { - QAbstractButton *button = static_cast<QAbstractButton *>(widget); - button->toggle(); -//! [5] //! [6] - } -//! [6] - -//! [7] - if (QAbstractButton *button = qobject_cast<QAbstractButton *>(widget)) - button->toggle(); -//! [7] } diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc index ed846aee83..81ce698735 100644 --- a/src/corelib/doc/src/custom-types.qdoc +++ b/src/corelib/doc/src/custom-types.qdoc @@ -61,7 +61,7 @@ The following \c Message class definition includes these members: - \snippet customtype/message.h custom type definition + \snippet tools/customtype/message.h custom type definition The class also provides a constructor for normal use and two public member functions that are used to obtain the private data. @@ -77,7 +77,7 @@ to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header file where it is defined: - \snippet customtype/message.h custom type meta-type declaration + \snippet tools/customtype/message.h custom type meta-type declaration This now makes it possible for \c Message values to be stored in QVariant objects and retrieved later. See the \l{Custom Type Example} for code that demonstrates @@ -104,19 +104,19 @@ The \l{Queued Custom Type Example} declares a \c Block class which is registered in the \c{main.cpp} file: - \snippet queuedcustomtype/main.cpp main start + \snippet threads/queuedcustomtype/main.cpp main start \dots - \snippet queuedcustomtype/main.cpp register meta-type for queued communications + \snippet threads/queuedcustomtype/main.cpp register meta-type for queued communications \dots - \snippet queuedcustomtype/main.cpp main finish + \snippet threads/queuedcustomtype/main.cpp main finish This type is later used in a signal-slot connection in the \c{window.cpp} file: - \snippet queuedcustomtype/window.cpp Window constructor start + \snippet threads/queuedcustomtype/window.cpp Window constructor start \dots - \snippet queuedcustomtype/window.cpp connecting signal with custom type + \snippet threads/queuedcustomtype/window.cpp connecting signal with custom type \dots - \snippet queuedcustomtype/window.cpp Window constructor finish + \snippet threads/queuedcustomtype/window.cpp Window constructor finish If a type is used in a queued connection without being registered, a warning will be printed at the console; for example: @@ -131,23 +131,23 @@ It is often quite useful to make a custom type printable for debugging purposes, as in the following code: - \snippet customtype/main.cpp printing a custom type + \snippet tools/customtype/main.cpp printing a custom type This is achieved by creating a streaming operator for the type, which is often defined in the header file for that type: - \snippet customtype/message.h custom type streaming operator + \snippet tools/customtype/message.h custom type streaming operator The implementation for the \c Message type in the \l{Custom Type Example} goes to some effort to make the printable representation as readable as possible: - \snippet customtype/message.cpp custom type streaming operator + \snippet tools/customtype/message.cpp custom type streaming operator The output sent to the debug stream can, of course, be made as simple or as complicated as you like. Note that the value returned by this function is the QDebug object itself, though this is often obtained by calling the - maybeSpace() member function of QDebug that pads out the stream with space + \l{QDebug::}{maybeSpace()} member function of QDebug that pads out the stream with space characters to make it more readable. \section1 Further Reading diff --git a/src/corelib/doc/src/eventsandfilters.qdoc b/src/corelib/doc/src/eventsandfilters.qdoc index a880cc8187..d9b2e35e19 100644 --- a/src/corelib/doc/src/eventsandfilters.qdoc +++ b/src/corelib/doc/src/eventsandfilters.qdoc @@ -194,7 +194,7 @@ \l{QCoreApplication::}{sendEvent()} processes the event immediately. When it returns, the event filters and/or the object itself have already processed the event. For many event classes there is a function - called isAccepted() that tells you whether the event was accepted + called \l{QEvent::}{isAccepted()} that tells you whether the event was accepted or rejected by the last handler that was called. \l{QCoreApplication::}{postEvent()} posts the event on a queue for diff --git a/src/corelib/doc/src/filestorage.qdoc b/src/corelib/doc/src/filestorage.qdoc index fb1279cea5..394d920923 100644 --- a/src/corelib/doc/src/filestorage.qdoc +++ b/src/corelib/doc/src/filestorage.qdoc @@ -30,15 +30,15 @@ \title File and Datastream Functions The QIODevice class is the base interface class of all I/O devices in -\l {Qt Core}. QIODevice provides both a common implementation and an +\l{Qt Core}. QIODevice provides both a common implementation and an abstract interface for devices that support reading and writing of blocks of data. The device can be a memory buffer, a file, or a datastream. Some subclasses like QFile have been implemented using a memory buffer for intermediate storing of data. This speeds up programs by reducing -read/write operations. Buffering makes functions like getChar() and putChar() -fast, as they can operate on the memory buffer instead of directly on the -device itself. +read/write operations. Buffering makes functions like \l{QFile::}{getChar()} and +\l{QFile::}{putChar()} fast, as they can operate on the memory buffer instead of +directly on the device itself. The QFile class provides functions for reading from and writing to files. A QFile may be used by itself or, more conveniently, with a QTextStream or @@ -48,6 +48,7 @@ QBuffer allows you to access a QByteArray using the QIODevice interface. The QByteArray is treated just as a standard random-accessed file. An example: +\code QBuffer buffer; char ch; @@ -58,12 +59,13 @@ An example: buffer.getChar(&ch); // ch == 't' buffer.getChar(&ch); // ch == ' ' buffer.getChar(&ch); // ch == 'r' +\endcode -Call open() to open the buffer. Then call write() or putChar() to write to -the buffer, and read(), readLine(), readAll(), or getChar() to read from it. -size() returns the current size of the buffer, and you can seek to arbitrary -positions in the buffer by calling seek(). When you are done with accessing -the buffer, call close(). +Call \l{QBuffer::}{open()} to open the buffer. Then call \l{QBuffer::}{write()} or \l{QBuffer::}{putChar()} to write to +the buffer, and \l{QBuffer::}{read()}, \l{QBuffer::}{readLine()}, \l{QBuffer::}{readAll()}, or \l{QBuffer::}{getChar()} to read from it. +\l{QBuffer::}{size()} returns the current size of the buffer, and you can seek to arbitrary +positions in the buffer by calling \l{QBuffer::}{seek()}. When you are done with accessing +the buffer, call \l{QBuffer::}{close()}. The QDataStream class provides serialization of binary data to a QIODevice. A data stream is a binary stream of encoded information which is 100% inde- @@ -91,7 +93,7 @@ There are three general ways to use QTextStream when reading text files: \li Character by character, by streaming into QChar or char types. This method is often used for convenient input handling when parsing files, independent of character encoding and end-of-line semantics. To skip - white space, call skipWhiteSpace(). + white space, call \l{QTextStream::}{skipWhiteSpace()}. \endlist QByteArray can be used to store both raw bytes (including \c{\0}) and traditional diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc index 70f0b88e06..8a6c7f53d9 100644 --- a/src/corelib/doc/src/objectmodel/properties.qdoc +++ b/src/corelib/doc/src/objectmodel/properties.qdoc @@ -226,7 +226,7 @@ In the example, the enumeration type that is the property type is declared in MyClass and registered with the \l{Meta-Object System} using the Q_ENUMS() macro. This makes the enumeration values - available as strings for use as in the call to setProperty(). Had + available as strings for use as in the call to \l{QObject::}{setProperty()}. Had the enumeration type been declared in another class, its fully qualified name (i.e., OtherClass::Priority) would be required, and that other class would also have to inherit QObject and register @@ -249,7 +249,7 @@ If the value is \e not compatible with the property's type, the property is \e not changed, and false is returned. But if the property with the given name doesn't exist in the QObject (i.e., - if it wasn't declared with Q_PROPERTY(), a new property with the + if it wasn't declared with Q_PROPERTY()), a new property with the given name and value is automatically added to the QObject, but false is still returned. This means that a return of false can't be used to determine whether a particular property was actually diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc index e894d547d0..f79e8a7dca 100644 --- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc +++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc @@ -36,7 +36,8 @@ Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by - other frameworks. + other frameworks. Signals and slots are made possible by Qt's + \l{The Meta-Object System}{meta-object system}. \tableofcontents @@ -48,17 +49,14 @@ if a user clicks a \uicontrol{Close} button, we probably want the window's \l{QWidget::close()}{close()} function to be called. - Older toolkits achieve this kind of communication using + Other toolkits achieve this kind of communication using callbacks. A callback is a pointer to a function, so if you want a processing function to notify you about some event you pass a pointer to another function (the callback) to the processing function. The processing function then calls the callback when - appropriate. Callbacks have two fundamental flaws: Firstly, they - are not type-safe. We can never be certain that the processing - function will call the callback with the correct arguments. - Secondly, the callback is strongly coupled to the processing - function since the processing function must know which callback - to call. + appropriate. While successful frameworks using this method do exist, + callbacks can be unintuitive and may suffer from problems in ensuring + the type-correctness of callback arguments. \section1 Signals and Slots @@ -112,87 +110,6 @@ Together, signals and slots make up a powerful component programming mechanism. - \section1 A Small Example - - A minimal C++ class declaration might read: - - \snippet signalsandslots/signalsandslots.h 0 - - A small QObject-based class might read: - - \snippet signalsandslots/signalsandslots.h 1 - \codeline - \snippet signalsandslots/signalsandslots.h 2 - \snippet signalsandslots/signalsandslots.h 3 - - The QObject-based version has the same internal state, and provides - public methods to access the state, but in addition it has support - for component programming using signals and slots. This class can - tell the outside world that its state has changed by emitting a - signal, \c{valueChanged()}, and it has a slot which other objects - can send signals to. - - All classes that contain signals or slots must mention - Q_OBJECT at the top of their declaration. They must also derive - (directly or indirectly) from QObject. - - Slots are implemented by the application programmer. - Here is a possible implementation of the \c{Counter::setValue()} - slot: - - \snippet signalsandslots/signalsandslots.cpp 0 - - The \c{emit} line emits the signal \c valueChanged() from the - object, with the new value as argument. - - In the following code snippet, we create two \c Counter objects - and connect the first object's \c valueChanged() signal to the - second object's \c setValue() slot using QObject::connect(): - - \snippet signalsandslots/signalsandslots.cpp 1 - \snippet signalsandslots/signalsandslots.cpp 2 - \codeline - \snippet signalsandslots/signalsandslots.cpp 3 - \snippet signalsandslots/signalsandslots.cpp 4 - - Calling \c{a.setValue(12)} makes \c{a} emit a - \c{valueChanged(12)} signal, which \c{b} will receive in its - \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then - \c{b} emits the same \c{valueChanged()} signal, but since no slot - has been connected to \c{b}'s \c{valueChanged()} signal, the - signal is ignored. - - Note that the \c{setValue()} function sets the value and emits - the signal only if \c{value != m_value}. This prevents infinite - looping in the case of cyclic connections (e.g., if - \c{b.valueChanged()} were connected to \c{a.setValue()}). - - By default, for every connection you make, a signal is emitted; - two signals are emitted for duplicate connections. You can break - all of these connections with a single disconnect() call. - If you pass the Qt::UniqueConnection \a type, the connection will only - be made if it is not a duplicate. If there is already a duplicate - (exact same signal to the exact same slot on the same objects), - the connection will fail and connect will return false - - This example illustrates that objects can work together without needing to - know any information about each other. To enable this, the objects only - need to be connected together, and this can be achieved with some simple - QObject::connect() function calls, or with \c{uic}'s - \l{Using a Designer UI File in Your Application#Automatic Connections} - {automatic connections} feature. - - \section1 Building the Example - - The C++ preprocessor changes or removes the \c{signals}, - \c{slots}, and \c{emit} keywords so that the compiler is - presented with standard C++. - - By running the \l moc on class definitions that contain signals - or slots, a C++ source file is produced which should be compiled - and linked with the other object files for the application. If - you use \l qmake, the makefile rules to automatically invoke \c - moc will be added to your project's makefile. \section1 Signals @@ -267,27 +184,77 @@ alongside a Qt-based application. To solve this problem, \c #undef the offending preprocessor symbol. - \section1 Meta-Object Information - The meta-object compiler (\l moc) parses the class declaration in - a C++ file and generates C++ code that initializes the - meta-object. The meta-object contains the names of all the signal - and slot members, as well as pointers to these functions. + \section1 A Small Example + + A minimal C++ class declaration might read: + + \snippet signalsandslots/signalsandslots.h 0 + + A small QObject-based class might read: + + \snippet signalsandslots/signalsandslots.h 1 + \codeline + \snippet signalsandslots/signalsandslots.h 2 + \snippet signalsandslots/signalsandslots.h 3 + + The QObject-based version has the same internal state, and provides + public methods to access the state, but in addition it has support + for component programming using signals and slots. This class can + tell the outside world that its state has changed by emitting a + signal, \c{valueChanged()}, and it has a slot which other objects + can send signals to. + + All classes that contain signals or slots must mention + Q_OBJECT at the top of their declaration. They must also derive + (directly or indirectly) from QObject. + + Slots are implemented by the application programmer. + Here is a possible implementation of the \c{Counter::setValue()} + slot: + + \snippet signalsandslots/signalsandslots.cpp 0 + + The \c{emit} line emits the signal \c valueChanged() from the + object, with the new value as argument. + + In the following code snippet, we create two \c Counter objects + and connect the first object's \c valueChanged() signal to the + second object's \c setValue() slot using QObject::connect(): - The meta-object contains additional information such as the - object's \l{QMetaObject::className()}{class name}. You can - also check if an object \l{QObject::inherits()}{inherits} - a specific class, for example: + \snippet signalsandslots/signalsandslots.cpp 1 + \snippet signalsandslots/signalsandslots.cpp 2 + \codeline + \snippet signalsandslots/signalsandslots.cpp 3 + \snippet signalsandslots/signalsandslots.cpp 4 + + Calling \c{a.setValue(12)} makes \c{a} emit a + \c{valueChanged(12)} signal, which \c{b} will receive in its + \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then + \c{b} emits the same \c{valueChanged()} signal, but since no slot + has been connected to \c{b}'s \c{valueChanged()} signal, the + signal is ignored. - \snippet signalsandslots/signalsandslots.cpp 5 - \snippet signalsandslots/signalsandslots.cpp 6 + Note that the \c{setValue()} function sets the value and emits + the signal only if \c{value != m_value}. This prevents infinite + looping in the case of cyclic connections (e.g., if + \c{b.valueChanged()} were connected to \c{a.setValue()}). - The meta-object information is also used by qobject_cast<T>(), which - is similar to QObject::inherits() but is less error-prone: + By default, for every connection you make, a signal is emitted; + two signals are emitted for duplicate connections. You can break + all of these connections with a single disconnect() call. + If you pass the Qt::UniqueConnection \a type, the connection will only + be made if it is not a duplicate. If there is already a duplicate + (exact same signal to the exact same slot on the same objects), + the connection will fail and connect will return false - \snippet signalsandslots/signalsandslots.cpp 7 + This example illustrates that objects can work together without needing to + know any information about each other. To enable this, the objects only + need to be connected together, and this can be achieved with some simple + QObject::connect() function calls, or with \c{uic}'s + \l{Using a Designer UI File in Your Application#Automatic Connections} + {automatic connections} feature. - See \l{Meta-Object System} for more information. \section1 A Real Example @@ -392,7 +359,7 @@ compatible with the slot's arguments. Arguments can also be implicitly converted by the compiler, if needed. - You can also connect to functors or C++11 lamdas: + You can also connect to functors or C++11 lambdas: \code connect(sender, &QObject::destroyed, [=](){ this->m_objects.remove(sender); }); diff --git a/src/corelib/doc/src/plugin-classes.qdoc b/src/corelib/doc/src/plugin-classes.qdoc new file mode 100644 index 0000000000..745e73151b --- /dev/null +++ b/src/corelib/doc/src/plugin-classes.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group plugins + \title Plugin Classes + \ingroup groups + + \brief Plugin related classes. + + These \l{Qt Core} classes deal with shared libraries, (for example, .so and DLL + files), and with Qt plugins. + + See the \l{How to Create Qt Plugins} page for more information. +*/ diff --git a/src/corelib/doc/src/plugins-howto.qdoc b/src/corelib/doc/src/plugins-howto.qdoc deleted file mode 100644 index 7dc0d01cce..0000000000 --- a/src/corelib/doc/src/plugins-howto.qdoc +++ /dev/null @@ -1,333 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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 Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group plugins - \title Plugin Classes - \ingroup groups - - \brief Plugin related classes. - - These \l{Qt Core} classes deal with shared libraries, (e.g. .so and DLL - files), and with Qt plugins. - - See the \l{How to Create Qt Plugins} page for more information. -*/ - -/*! - \page plugins-howto.html - \title How to Create Qt Plugins - \brief A guide to creating plugins to extend Qt applications and - functionality provided by Qt. - - \ingroup frameworks-technologies - \ingroup qt-basic-concepts - - - \keyword QT_DEBUG_PLUGINS - \keyword QT_NO_PLUGIN_CHECK - - Qt provides two APIs for creating plugins: - - \list - \li A higher-level API for writing extensions to Qt itself: custom database - drivers, image formats, text codecs, custom styles, etc. - \li A lower-level API for extending Qt applications. - \endlist - - For example, if you want to write a custom QStyle subclass and - have Qt applications load it dynamically, you would use the - higher-level API. - - Since the higher-level API is built on top of the lower-level API, - some issues are common to both. - - If you want to provide plugins for use with Qt Designer, see the Qt Designer - module documentation. - - Topics: - - \tableofcontents - - \section1 The Higher-Level API: Writing Qt Extensions - - Writing a plugin that extends Qt itself is achieved by - subclassing the appropriate plugin base class, implementing a few - functions, and adding a macro. - - There are several plugin base classes. Derived plugins are stored - by default in sub-directories of the standard plugin directory. Qt - will not find plugins if they are not stored in the right - directory. - - \table - \header \li Base Class \li Directory Name \li Key Case Sensitivity - \row \li QAccessibleBridgePlugin \li \c accessiblebridge \li Case Sensitive - \row \li QAccessiblePlugin \li \c accessible \li Case Sensitive - \row \li QDecorationPlugin \li \c decorations \li Case Insensitive - \row \li QFontEnginePlugin \li \c fontengines \li Case Insensitive - \row \li QIconEnginePlugin \li \c iconengines \li Case Insensitive - \row \li QImageIOPlugin \li \c imageformats \li Case Sensitive - \row \li QInputContextPlugin \li \c inputmethods \li Case Sensitive - \row \li QKbdDriverPlugin \li \c kbddrivers \li Case Insensitive - \row \li QMouseDriverPlugin \li \c mousedrivers \li Case Insensitive - \row \li QScreenDriverPlugin \li \c gfxdrivers \li Case Insensitive - \row \li QScriptExtensionPlugin \li \c script \li Case Sensitive - \row \li QSqlDriverPlugin \li \c sqldrivers \li Case Sensitive - \row \li QStylePlugin \li \c styles \li Case Insensitive - \row \li QTextCodecPlugin \li \c codecs \li Case Sensitive - \endtable - - Suppose that you have a new style class called \c MyStyle that you - want to make available as a plugin. The required code is - straightforward, here is the class definition (\c - mystyleplugin.h): - - \snippet code/doc_src_plugins-howto.cpp 0 - - Ensure that the class implementation is located in a \c .cpp file: - - \snippet code/doc_src_plugins-howto.cpp 1 - - (Note that QStylePlugin is case insensitive, and the lower-case - version of the key is used in our - \l{QStylePlugin::create()}{create()} implementation; most other - plugins are case sensitive.) - - In addition a \c mystyleplugin.json file containing meta data - describing the plugin is required for most plugins. For style - plugins it simply contains a list of styles that can be created - by the plugin: - - \snippet code/doc_src_plugins-howto.qdoc 6 - - The type of information that needs to be provided in the json file - is plugin dependent, please see the class documentation for - details on the information that needs to be contained in the - file. - - For database drivers, image formats, text codecs, and most other - plugin types, no explicit object creation is required. Qt will - find and create them as required. Styles are an exception, since - you might want to set a style explicitly in code. To apply a - style, use code like this: - - \snippet code/doc_src_plugins-howto.cpp 2 - - Some plugin classes require additional functions to be - implemented. See the class documentation for details of the - virtual functions that must be reimplemented for each type of - plugin. - - The \l{Style Plugin Example} shows how to implement a plugin - that extends the QStylePlugin base class. - - \section1 The Lower-Level API: Extending Qt Applications - - Not only Qt itself but also Qt application can be extended - through plugins. This requires the application to detect and load - plugins using QPluginLoader. In that context, plugins may provide - arbitrary functionality and are not limited to database drivers, - image formats, text codecs, styles, and the other types of plugin - that extend Qt's functionality. - - Making an application extensible through plugins involves the - following steps: - - \list 1 - \li Define a set of interfaces (classes with only pure virtual - functions) used to talk to the plugins. - \li Use the Q_DECLARE_INTERFACE() macro to tell Qt's - \l{meta-object system} about the interface. - \li Use QPluginLoader in the application to load the plugins. - \li Use qobject_cast() to test whether a plugin implements a given - interface. - \endlist - - Writing a plugin involves these steps: - - \list 1 - \li Declare a plugin class that inherits from QObject and from the - interfaces that the plugin wants to provide. - \li Use the Q_INTERFACES() macro to tell Qt's \l{meta-object - system} about the interfaces. - \li Export the plugin using the Q_PLUGIN_METADATA() macro. - \li Build the plugin using a suitable \c .pro file. - \endlist - - For example, here's the definition of an interface class: - - \snippet plugins/interfaces.h 2 - - Here's the definition of a plugin class that implements that - interface: - - \snippet plugins/extrafiltersplugin.h 0 - - The \l{tools/plugandpaint}{Plug & Paint} example documentation - explains this process in detail. See also \l{Creating Custom - Widgets for Qt Designer} for information about issues that are - specific to Qt Designer. You can also take a look at the - \l{Echo Plugin Example} which is a more trivial example on - how to implement a plugin that extends Qt applications. - Please note that a QCoreApplication must have been initialized - before plugins can be loaded. - - \section1 Locating Plugins - - Qt applications automatically know which plugins are available, - because plugins are stored in the standard plugin subdirectories. - Because of this applications don't require any code to find and load - plugins, since Qt handles them automatically. - - During development, the directory for plugins is \c{QTDIR/plugins} - (where \c QTDIR is the directory where Qt is installed), with each - type of plugin in a subdirectory for that type, e.g. \c styles. If - you want your applications to use plugins and you don't want to use - the standard plugins path, have your installation process - determine the path you want to use for the plugins, and save the - path, e.g. using QSettings, for the application to read when it - runs. The application can then call - QCoreApplication::addLibraryPath() with this path and your - plugins will be available to the application. Note that the final - part of the path (e.g., \c styles) cannot be changed. - - If you want the plugin to be loadable then one approach is to - create a subdirectory under the application and place the plugin - in that directory. If you distribute any of the plugins that come - with Qt (the ones located in the \c plugins directory), you must - copy the sub-directory under \c plugins where the plugin is - located to your applications root folder (i.e., do not include the - \c plugins directory). - - For more information about deployment, - see the \l {Deploying Qt Applications} and \l {Deploying Plugins} - documentation. - - \section1 Static Plugins - - The normal and most flexible way to include a plugin with an - application is to compile it into a dynamic library that is shipped - separately, and detected and loaded at runtime. - - Plugins can be linked statically into your application. If you - build the static version of Qt, this is the only option for - including Qt's predefined plugins. Using static plugins makes the - deployment less error-prone, but has the disadvantage that no - functionality from plugins can be added without a complete rebuild - and redistribution of the application. - - When compiled as a static library, Qt provides the following - static plugins: - - \table - \header \li Plugin name \li Type \li Description - \row \li \c qtaccessiblewidgets \li Accessibility \li Accessibility for Qt widgets - \row \li \c qgif \li Image formats \li GIF - \row \li \c qjpeg \li Image formats \li JPEG - \row \li \c qmng \li Image formats \li MNG - \row \li \c qico \li Image formats \li ICO - \row \li \c qsvg \li Image formats \li SVG - \row \li \c qtiff \li Image formats \li TIFF - \row \li \c qsqldb2 \li SQL driver \li IBM DB2 - \row \li \c qsqlibase \li SQL driver \li Borland InterBase - \row \li \c qsqlite \li SQL driver \li SQLite version 3 - \row \li \c qsqlite2 \li SQL driver \li SQLite version 2 - \row \li \c qsqlmysql \li SQL driver \li MySQL - \row \li \c qsqloci \li SQL driver \li Oracle (OCI) - \row \li \c qsqlodbc \li SQL driver \li Open Database Connectivity (ODBC) - \row \li \c qsqlpsql \li SQL driver \li PostgreSQL - \row \li \c qsqltds \li SQL driver \li Sybase Adaptive Server (TDS) - \endtable - - To link those plugins statically, you need to add - the required plugins to your build using \c QTPLUGIN. - - In the \c .pro file for your application, you need the following - entry: - - \snippet code/doc_src_plugins-howto.pro 5 - - qmake automatically adds the plugins to QTPLUGIN that are typically - needed by the used Qt modules (see \c QT), while more specialized - plugins need to be added manually. - The default list of automatically added plugins can be overridden - per type. - For example, to link the minimal plugin instead of the default Qt - platform adaptation plugin, use: - - \snippet code/doc_src_plugins-howto.pro 4 - - If you want neither the default nor the minimal QPA plugin to be - linked automatically, use: - - \snippet code/doc_src_plugins-howto.pro 6 - - The defaults are tuned towards an optimal out-of-the-box experience, - but may unnecessarily bloat the application. - It is recommended to inspect the linker command line built by qmake - and eliminate unnecessary plugins. - - \section2 Details of Linking Static Plugins - - To cause static plugins actually being linked and instantiated, - Q_IMPORT_PLUGIN() macros are also needed in application code, - but those are automatically generated by qmake and added to - your application project. - - If you do not want all plugins added to QTPLUGIN to be automatically - linked, remove \c import_plugins from the \c CONFIG variable: - - \snippet code/doc_src_plugins-howto.pro 7 - - \section2 Creating Static Plugins - - It is also possible to create your own static plugins, by - following these steps: - - \list 1 - \li Add \c{CONFIG += static} to your plugin's \c .pro file. - \li Use the Q_IMPORT_PLUGIN() macro in your application. - \li Link your application with your plugin library using \c LIBS - in the \c .pro file. - \endlist - - See the \l{tools/plugandpaint}{Plug & Paint} example and the - associated \l{tools/plugandpaintplugins/basictools}{Basic Tools} - plugin for details on how to do this. - - \note If you are not using qmake to build your plugin you need - to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is - defined. - - \section1 Deploying and Debugging Plugins - - The \l{Deploying Plugins} document covers the process of deploying - plugins with applications and debugging them when problems arise. - - \sa QPluginLoader, QLibrary, {Plug & Paint Example} -*/ |