From 20a6b6b3ca3f2bb81c71d6b18b84510b27d4675a Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Tue, 9 Sep 2014 13:24:30 +0200 Subject: Doc: corrected link/autolink errors in corelib/doc/src MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task-number: QTBUG-40362 Change-Id: I0ff1523c76724e0662bafed08515ea06bbdd8381 Reviewed-by: Topi Reiniö --- src/corelib/doc/src/custom-types.qdoc | 2 +- src/corelib/doc/src/eventsandfilters.qdoc | 2 +- src/corelib/doc/src/filestorage.qdoc | 22 ++++++++++++---------- 3 files changed, 14 insertions(+), 12 deletions(-) (limited to 'src/corelib/doc') diff --git a/src/corelib/doc/src/custom-types.qdoc b/src/corelib/doc/src/custom-types.qdoc index ed846aee83..bac4a90829 100644 --- a/src/corelib/doc/src/custom-types.qdoc +++ b/src/corelib/doc/src/custom-types.qdoc @@ -147,7 +147,7 @@ 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 -- cgit v1.2.3 From 974c2108352d1136835a615d3b56b827d6ef99dd Mon Sep 17 00:00:00 2001 From: Matti Paaso Date: Thu, 21 Aug 2014 16:51:22 +0300 Subject: Update license headers and add new license files - Renamed LICENSE.LGPL to LICENSE.LGPLv21 - Added LICENSE.LGPLv3 - Removed LICENSE.GPL Change-Id: Iec3406e3eb3f133be549092015cefe33d259a3f2 Reviewed-by: Iikka Eklund --- .../snippets/code/src_corelib_io_qstorageinfo.cpp | 28 ++++++++-------------- 1 file changed, 10 insertions(+), 18 deletions(-) (limited to 'src/corelib/doc') diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp index e5e8c1e86a..bba3703325 100644 --- a/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_io_qstorageinfo.cpp @@ -5,36 +5,28 @@ ** ** This file is part of the QtCore module of the Qt Toolkit. ** -** $QT_BEGIN_LICENSE:LGPL$ +** $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 +** 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. +** 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 +** 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$ ** ****************************************************************************/ -- cgit v1.2.3 From f5d58c04421fccefba86a9f6ed2339ec685f897e Mon Sep 17 00:00:00 2001 From: Sze Howe Koh Date: Sun, 31 Aug 2014 21:42:48 +1000 Subject: Doc: Remove irrelevant sections from "Signals & Slots" - This article is not the right place to describe the low-level mechanisms of moc and qmake, or to discuss QMetaObject features that are unrelated to signals and slots. - Most users never need to run moc directly. - The current content only mentions qmake for moc automation, but CMake, QBS, and the Visual Studio Add-In can also do that. In light of the above 3 points, let's simply link to the "Meta-Object System" article for those who are interested in the behind-the-scenes details. Most of the content deleted by this patch are already discussed in detail in the articles "The Meta-Object System" and "Using the Meta- Object Compiler (moc)" (the former links to the latter). The exception is Snippet 5 -- this is deleted without replacement because qobject_cast() is a much safer alternative to QMetaObject::inherits() with static_cast(), so we should encourage the former. Change-Id: I638c888cedfcdfb818747edeb806213ebd54dfb6 Reviewed-by: Jerome Pasion Reviewed-by: Olivier Goffart --- .../snippets/signalsandslots/signalsandslots.cpp | 17 ----------- .../doc/src/objectmodel/signalsandslots.qdoc | 35 ++-------------------- 2 files changed, 2 insertions(+), 50 deletions(-) (limited to 'src/corelib/doc') 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 - #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(new QObject(0)); -//! [5] - if (widget->inherits("QAbstractButton")) { - QAbstractButton *button = static_cast(widget); - button->toggle(); -//! [5] //! [6] - } -//! [6] - -//! [7] - if (QAbstractButton *button = qobject_cast(widget)) - button->toggle(); -//! [7] } diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc index d290d7dc37..6f0e230943 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 @@ -182,17 +183,6 @@ \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 +257,6 @@ 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. - - 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 5 - \snippet signalsandslots/signalsandslots.cpp 6 - - The meta-object information is also used by qobject_cast(), which - is similar to QObject::inherits() but is less error-prone: - - \snippet signalsandslots/signalsandslots.cpp 7 - - See \l{Meta-Object System} for more information. \section1 A Real Example -- cgit v1.2.3 From a72d585f9b3327d301a605e9500058670ed7a5f5 Mon Sep 17 00:00:00 2001 From: Sze Howe Koh Date: Mon, 1 Sep 2014 17:52:01 +0800 Subject: Doc: Restructure "Signal & Slots" article Put sections with similar content together: - Put "A Small Example" next to "A Real Example". - Put "Signals and Slots", "Signals", and "Slots" together. Altogether, these 3 sections contain lots of repeated content and should be consolidated in a future commit. This patch only moves content around without adding, removing, or modifying content. Change-Id: Ic6bf6a8b51f4785a8bbe6d230c2934f2c952104d Reviewed-by: Jerome Pasion --- .../doc/src/objectmodel/signalsandslots.qdoc | 141 +++++++++++---------- 1 file changed, 71 insertions(+), 70 deletions(-) (limited to 'src/corelib/doc') diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc index 6f0e230943..6dcf567c2e 100644 --- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc +++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc @@ -113,76 +113,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 Signals @@ -258,6 +188,77 @@ #undef the offending preprocessor symbol. + \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 A Real Example Here is a simple commented example of a widget. -- cgit v1.2.3