diff options
141 files changed, 5576 insertions, 248 deletions
diff --git a/doc/src/snippets/code/src_gui_embedded_qwindowsystem_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qwindowsystem_qws.cpp deleted file mode 100644 index 66308f3405..0000000000 --- a/doc/src/snippets/code/src_gui_embedded_qwindowsystem_qws.cpp +++ /dev/null @@ -1,85 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** 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 Nokia Corporation 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$ -** -****************************************************************************/ - -//! [0] -bool MyScreenSaver::save( int level ) -{ - switch ( level ) { - case 0: - if ( dim_enabled ) { - // dim the screen - } - return true; - case 1: - if ( screenoff_enabled ) { - // turn off the screen - } - return true; - case 2: - if ( suspend_enabled ) { - // suspend - } - return true; - default: - return false; - } -} - -... - -int timings[4]; -timings[0] = 5000; // dim after 5 seconds -timings[1] = 10000; // light off after 15 seconds -timings[2] = 45000; // suspend after 60 seconds -timings[3] = 0; -QWSServer::setScreenSaverIntervals( timings ); - -// ignore the key/mouse event that turns on the screen -int blocklevel = 1; -if ( !screenoff_enabled ) { - // screenoff is disabled, ignore the key/mouse event that wakes from suspend - blocklevel = 2; - if ( !suspend_enabled ) { - // suspend is disabled, never ignore events - blocklevel = -1; - } -} -QWSServer::setScreenSaverBlockLevel( blocklevel ); -//! [0] diff --git a/doc/src/images/resources.png b/src/corelib/doc/images/resources.png Binary files differindex eb7af96d77..eb7af96d77 100644 --- a/doc/src/images/resources.png +++ b/src/corelib/doc/images/resources.png diff --git a/doc/src/snippets/code/doc_src_resources.cpp b/src/corelib/doc/snippets/code/doc_src_resources.cpp index f401add728..f401add728 100644 --- a/doc/src/snippets/code/doc_src_resources.cpp +++ b/src/corelib/doc/snippets/code/doc_src_resources.cpp diff --git a/doc/src/snippets/code/doc_src_resources.qdoc b/src/corelib/doc/snippets/code/doc_src_resources.qdoc index c51dbbcbf3..c51dbbcbf3 100644 --- a/doc/src/snippets/code/doc_src_resources.qdoc +++ b/src/corelib/doc/snippets/code/doc_src_resources.qdoc diff --git a/src/corelib/doc/src/io.qdoc b/src/corelib/doc/src/io.qdoc new file mode 100644 index 0000000000..dfe9be2b3c --- /dev/null +++ b/src/corelib/doc/src/io.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group io + \title Input/Output and Networking + \ingroup groups + + \brief Classes providing file input and output along with directory and + network handling. + + These classes are used to handle input and output to and from external + devices, processes, files etc. as well as manipulating files and directories. +*/ + diff --git a/doc/src/network/files-and-resources/resources.qdoc b/src/corelib/doc/src/resource-system.qdoc index 1d0fc51631..89a099a1c1 100644 --- a/doc/src/network/files-and-resources/resources.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -26,18 +26,6 @@ ****************************************************************************/ /*! - \group io - \title Input/Output and Networking - \ingroup groups - - \brief Classes providing file input and output along with directory and - network handling. - - These classes are used to handle input and output to and from external - devices, processes, files etc. as well as manipulating files and directories. -*/ - -/*! \page resources.html \title The Qt Resource System \ingroup qt-network @@ -89,14 +77,14 @@ is \c images/cut.png. This can be changed using the \c file tag's \c alias attribute: - \snippet doc/src/snippets/code/doc_src_resources.qdoc 0 + \snippet code/doc_src_resources.qdoc 0 The file is then accessible as \c :/cut-img.png from the application. It is also possible to specify a path prefix for all files in the \c .qrc file using the \c qresource tag's \c prefix attribute: - \snippet doc/src/snippets/code/doc_src_resources.qdoc 1 + \snippet code/doc_src_resources.qdoc 1 In this case, the file is accessible as \c :/myresources/cut-img.png. @@ -106,7 +94,7 @@ attribute to the \c qresource tag, specifying a suitable locale string. For example: - \snippet doc/src/snippets/code/doc_src_resources.qdoc 2 + \snippet code/doc_src_resources.qdoc 2 If the user's locale is French (i.e., QLocale::system().name() returns "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg @@ -126,11 +114,11 @@ For example, a set of resource data specified in a \c .qrc file can be compiled in the following way: - \snippet doc/src/snippets/code/doc_src_resources.qdoc 3 + \snippet code/doc_src_resources.qdoc 3 In the application, this resource would be registered with code like this: - \snippet doc/src/snippets/code/doc_src_resources.cpp 4 + \snippet code/doc_src_resources.cpp 4 \section2 Compiled-In Resources @@ -138,7 +126,7 @@ mentioned in the application's \c .pro file so that \c qmake knows about it. For example: - \snippet examples/mainwindows/application/application.pro 0 + \snippet mainwindows/application/application.pro 0 \c qmake will produce make rules to generate a file called \c qrc_application.cpp that is linked into the application. This @@ -183,7 +171,7 @@ pass a resource path instead of a file name to the QIcon, QImage, or QPixmap constructor: - \snippet examples/mainwindows/application/mainwindow.cpp 21 + \snippet mainwindows/application/mainwindow.cpp 21 See the \l{mainwindows/application}{Application} example for an actual application that uses Qt's resource system to store its @@ -205,7 +193,7 @@ Q_INIT_RESOURCE() with the base name of the \c .qrc file. For example: - \snippet doc/src/snippets/code/doc_src_resources.cpp 5 + \snippet code/doc_src_resources.cpp 5 Similarly, if you must unload a set of resources explicitly (because a plugin is being unloaded or the resources are not valid diff --git a/src/corelib/global/qlogging.cpp b/src/corelib/global/qlogging.cpp index 52ffae5f98..ed845745be 100644 --- a/src/corelib/global/qlogging.cpp +++ b/src/corelib/global/qlogging.cpp @@ -737,7 +737,7 @@ void qWinMessageHandler2(QtMsgType t, const QMessageLogContext &context, This is a typedef for a pointer to a function with the following signature: - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 7 + \snippet code/src_corelib_global_qglobal.cpp 7 This typedef is deprecated, you should use QtMessageHandler instead. \sa QtMsgType, QtMessageHandler, qInstallMsgHandler(), qInstallMessageHandler() @@ -751,7 +751,7 @@ void qWinMessageHandler2(QtMsgType t, const QMessageLogContext &context, This is a typedef for a pointer to a function with the following signature: - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 49 + \snippet code/src_corelib_global_qglobal.cpp 49 \sa QtMsgType, qInstallMessageHandler() */ @@ -785,7 +785,7 @@ void qWinMessageHandler2(QtMsgType t, const QMessageLogContext &context, Example: - \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 23 + \snippet code/src_corelib_global_qglobal.cpp 23 \sa QtMessageHandler, QtMsgType, qDebug(), qWarning(), qCritical(), qFatal(), {Debugging Techniques} diff --git a/src/corelib/io/qfiledevice.cpp b/src/corelib/io/qfiledevice.cpp index 17eedb0bdd..e1f1db9ead 100644 --- a/src/corelib/io/qfiledevice.cpp +++ b/src/corelib/io/qfiledevice.cpp @@ -146,12 +146,12 @@ void QFileDevicePrivate::setError(QFileDevice::FileError err, int errNum) handling considerably. It is possible to force permission checking on NTFS by including the following code in your source: - \snippet doc/src/snippets/ntfsp.cpp 0 + \snippet ntfsp.cpp 0 Permission checking is then turned on and off by incrementing and decrementing \c qt_ntfs_permission_lookup by 1. - \snippet doc/src/snippets/ntfsp.cpp 1 + \snippet ntfsp.cpp 1 */ //************* QFileDevice diff --git a/src/corelib/io/qurlquery.cpp b/src/corelib/io/qurlquery.cpp index 2e2db11558..5625aebd3c 100644 --- a/src/corelib/io/qurlquery.cpp +++ b/src/corelib/io/qurlquery.cpp @@ -511,7 +511,7 @@ QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding) const If \a valueDelimiter is set to '(' and \a pairDelimiter is ')', the above query string would instead be represented like this: - \snippet doc/src/snippets/code/src_corelib_io_qurl.cpp 4 + \snippet code/src_corelib_io_qurl.cpp 4 \note Non-standard delimiters should be chosen from among what RFC 3986 calls "sub-delimiters". They are: diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp index 10dcff92c7..3172014363 100644 --- a/src/corelib/tools/qhash.cpp +++ b/src/corelib/tools/qhash.cpp @@ -838,7 +838,7 @@ void QHashData::checkSanity() operator==() and a qHash() implementation. Example: - \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 13 + \snippet code/src_corelib_tools_qhash.cpp 13 In the example above, we've relied on Qt's global qHash(const QString &, uint) to give us a hash value for the employee's name, and diff --git a/src/corelib/tools/qstringlist.cpp b/src/corelib/tools/qstringlist.cpp index c25d326b9d..0b0aeb50c0 100644 --- a/src/corelib/tools/qstringlist.cpp +++ b/src/corelib/tools/qstringlist.cpp @@ -404,8 +404,8 @@ void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegExp &r For example: - \snippet doc/src/snippets/qstringlist/main.cpp 5 - \snippet doc/src/snippets/qstringlist/main.cpp 16 + \snippet qstringlist/main.cpp 5 + \snippet qstringlist/main.cpp 16 For regular expressions that contain capturing groups, occurrences of \b{\\1}, \b{\\2}, ..., in \a after are @@ -413,8 +413,8 @@ void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegExp &r For example: - \snippet doc/src/snippets/qstringlist/main.cpp 5 - \snippet doc/src/snippets/qstringlist/main.cpp 17 + \snippet qstringlist/main.cpp 5 + \snippet qstringlist/main.cpp 17 */ void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegularExpression &re, const QString &after) { diff --git a/src/gui/doc/images/qrect-diagram-zero.png b/src/gui/doc/images/qrect-diagram-zero.png Binary files differnew file mode 100644 index 0000000000..90e3db0c41 --- /dev/null +++ b/src/gui/doc/images/qrect-diagram-zero.png diff --git a/src/gui/doc/images/qrectf-diagram-one.png b/src/gui/doc/images/qrectf-diagram-one.png Binary files differnew file mode 100644 index 0000000000..842289ce07 --- /dev/null +++ b/src/gui/doc/images/qrectf-diagram-one.png diff --git a/src/gui/doc/images/qrectf-diagram-three.png b/src/gui/doc/images/qrectf-diagram-three.png Binary files differnew file mode 100644 index 0000000000..e05106a7e1 --- /dev/null +++ b/src/gui/doc/images/qrectf-diagram-three.png diff --git a/src/gui/doc/images/qrectf-diagram-two.png b/src/gui/doc/images/qrectf-diagram-two.png Binary files differnew file mode 100644 index 0000000000..192d00df79 --- /dev/null +++ b/src/gui/doc/images/qrectf-diagram-two.png diff --git a/doc/src/snippets/code/doc_src_coordsys.cpp b/src/gui/doc/snippets/code/doc_src_coordsys.cpp index b677d28a50..b677d28a50 100644 --- a/doc/src/snippets/code/doc_src_coordsys.cpp +++ b/src/gui/doc/snippets/code/doc_src_coordsys.cpp diff --git a/src/gui/doc/src/coordsys.qdoc b/src/gui/doc/src/coordsys.qdoc index 655dbf7cf3..bfa046f7fb 100644 --- a/src/gui/doc/src/coordsys.qdoc +++ b/src/gui/doc/src/coordsys.qdoc @@ -97,10 +97,10 @@ \row \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 0 + \snippet code/doc_src_coordsys.cpp 0 \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 1 + \snippet code/doc_src_coordsys.cpp 1 \endtable When rendering with a pen with an even number of pixels, the @@ -163,10 +163,10 @@ \row \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 2 + \snippet code/doc_src_coordsys.cpp 2 \li - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 3 + \snippet code/doc_src_coordsys.cpp 3 \endtable \section1 Transformations @@ -238,7 +238,7 @@ \row \li {2,1} - \snippet examples/widgets/analogclock/analogclock.cpp 9 + \snippet widgets/analogclock/analogclock.cpp 9 First, we set up the painter. We translate the coordinate system so that point (0, 0) is in the widget's center, instead of being @@ -253,7 +253,7 @@ See also the \l {Window-Viewport Conversion} section. - \snippet examples/widgets/analogclock/analogclock.cpp 18 + \snippet widgets/analogclock/analogclock.cpp 18 We draw the clock's hour hand by rotating the coordinate system and calling QPainter::drawConvexPolygon(). Thank's to the @@ -268,14 +268,14 @@ the code guarantees that the code that follows won't be disturbed by the transformations we've used. - \snippet examples/widgets/analogclock/analogclock.cpp 24 + \snippet widgets/analogclock/analogclock.cpp 24 We do the same for the clock's minute hand, which is defined by the four points (1, 0), (0, 1), (-1, 0), and (0, -40). These coordinates specify a hand that is thinner and longer than the minute hand. - \snippet examples/widgets/analogclock/analogclock.cpp 27 + \snippet widgets/analogclock/analogclock.cpp 27 Finally, we draw the clock face, which consists of twelve short lines at 30-degree intervals. At the end of that, the painter is @@ -319,7 +319,7 @@ -50) to (50, 50) with (0, 0) in the center by calling the QPainter::setWindow() function: - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 4 + \snippet code/doc_src_coordsys.cpp 4 Now, the logical coordinates (-50,-50) correspond to the paint device's physical coordinates (0, 0). Independent of the paint @@ -333,7 +333,7 @@ viewport and "window" maintain the same aspect ratio to prevent deformation: - \snippet doc/src/snippets/code/doc_src_coordsys.cpp 5 + \snippet code/doc_src_coordsys.cpp 5 If we make the logical coordinate system a square, we should also make the viewport a square using the QPainter::setViewport() diff --git a/src/gui/kernel/qkeysequence.cpp b/src/gui/kernel/qkeysequence.cpp index 635e3dadca..d03294f246 100644 --- a/src/gui/kernel/qkeysequence.cpp +++ b/src/gui/kernel/qkeysequence.cpp @@ -177,7 +177,7 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni more modifiers, such as Qt::SHIFT, Qt::CTRL, Qt::ALT and Qt::META. \endlist - For example, \gui{Ctrl P} might be a sequence used as a shortcut for + For example, \uicontrol{Ctrl P} might be a sequence used as a shortcut for printing a document, and can be specified in any of the following ways: @@ -185,8 +185,8 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni Note that, for letters, the case used in the specification string does not matter. In the above examples, the user does not need to - hold down the \key{Shift} key to activate a shortcut specified - with "Ctrl+P". However, for other keys, the use of \key{Shift} as + hold down the \uicontrol{Shift} key to activate a shortcut specified + with "Ctrl+P". However, for other keys, the use of \uicontrol{Shift} as an unspecified extra modifier key can lead to confusion for users of an application whose keyboards have different layouts to those used by the developers. See the \l{Keyboard Layout Issues} section @@ -207,9 +207,9 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni as Qt::Key_A. \b{Note:} On Mac OS X, references to "Ctrl", Qt::CTRL, Qt::Control - and Qt::ControlModifier correspond to the \key Command keys on the + and Qt::ControlModifier correspond to the \uicontrol Command keys on the Macintosh keyboard, and references to "Meta", Qt::META, Qt::Meta and - Qt::MetaModifier correspond to the \key Control keys. Developers on + Qt::MetaModifier correspond to the \uicontrol Control keys. Developers on Mac OS X can use the same shortcut descriptions across all platforms, and their applications will automatically work as expected on Mac OS X. @@ -220,9 +220,9 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni setting up actions in a typical application. The table below shows some common key sequences that are often used for these standard shortcuts by applications on four widely-used platforms. Note - that on Mac OS X, the \key Ctrl value corresponds to the \key - Command keys on the Macintosh keyboard, and the \key Meta value - corresponds to the \key Control keys. + that on Mac OS X, the \uicontrol Ctrl value corresponds to the \uicontrol + Command keys on the Macintosh keyboard, and the \uicontrol Meta value + corresponds to the \uicontrol Control keys. \table \header \li StandardKey \li Windows \li Mac OS X \li KDE \li GNOME @@ -302,23 +302,23 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni Many key sequence specifications are chosen by developers based on the layout of certain types of keyboard, rather than choosing keys that - represent the first letter of an action's name, such as \key{Ctrl S} - ("Ctrl+S") or \key{Ctrl C} ("Ctrl+C"). + represent the first letter of an action's name, such as \uicontrol{Ctrl S} + ("Ctrl+S") or \uicontrol{Ctrl C} ("Ctrl+C"). Additionally, because certain symbols can only be entered with the help of modifier keys on certain keyboard layouts, key sequences intended for use with one keyboard layout may map to a different key, map to no keys at all, or require an additional modifier key to be used on different keyboard layouts. - For example, the shortcuts, \key{Ctrl plus} and \key{Ctrl minus}, are often + For example, the shortcuts, \uicontrol{Ctrl plus} and \uicontrol{Ctrl minus}, are often used as shortcuts for zoom operations in graphics applications, and these may be specified as "Ctrl++" and "Ctrl+-" respectively. However, the way these shortcuts are specified and interpreted depends on the keyboard layout. - Users of Norwegian keyboards will note that the \key{+} and \key{-} keys + Users of Norwegian keyboards will note that the \uicontrol{+} and \uicontrol{-} keys are not adjacent on the keyboard, but will still be able to activate both - shortcuts without needing to press the \key{Shift} key. However, users - with British keyboards will need to hold down the \key{Shift} key - to enter the \key{+} symbol, making the shortcut effectively the same as + shortcuts without needing to press the \uicontrol{Shift} key. However, users + with British keyboards will need to hold down the \uicontrol{Shift} key + to enter the \uicontrol{+} symbol, making the shortcut effectively the same as "Ctrl+Shift+=". Although some developers might resort to fully specifying all the modifiers @@ -327,9 +327,9 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni For example, a developer using a British keyboard may decide to specify "Ctrl+Shift+=" as the key sequence in order to create a shortcut that - coincidentally behaves in the same way as \key{Ctrl plus}. However, the - \key{=} key needs to be accessed using the \key{Shift} key on Norwegian - keyboard, making the required shortcut effectively \key{Ctrl Shift Shift =} + coincidentally behaves in the same way as \uicontrol{Ctrl plus}. However, the + \uicontrol{=} key needs to be accessed using the \uicontrol{Shift} key on Norwegian + keyboard, making the required shortcut effectively \uicontrol{Ctrl Shift Shift =} (an impossible key combination). As a result, both human-readable strings and hard-coded key codes @@ -351,7 +351,7 @@ void Q_GUI_EXPORT qt_set_sequence_auto_mnemonic(bool b) { qt_sequence_no_mnemoni key codes, can be created by using the multiple argument constructor, or by passing a human-readable string of comma-separated key sequences. - For example, the key sequence, \key{Ctrl X} followed by \key{Ctrl C}, can + For example, the key sequence, \uicontrol{Ctrl X} followed by \uicontrol{Ctrl C}, can be specified using either of the following ways: \snippet code/src_gui_kernel_qkeysequence.cpp 1 diff --git a/src/gui/text/qabstracttextdocumentlayout.cpp b/src/gui/text/qabstracttextdocumentlayout.cpp index e14cfe0f82..45903f678c 100644 --- a/src/gui/text/qabstracttextdocumentlayout.cpp +++ b/src/gui/text/qabstracttextdocumentlayout.cpp @@ -120,7 +120,7 @@ QT_BEGIN_NAMESPACE and QTextObjectInterface. QObject must be the first class inherited. For instance: - \snippet examples/richtext/textobject/svgtextobject.h 1 + \snippet richtext/textobject/svgtextobject.h 1 The data of a text object is usually stored in the QTextCharFormat using QTextCharFormat::setProperty(), and then retrieved with diff --git a/doc/src/images/tcpstream.png b/src/network/doc/images/tcpstream.png Binary files differindex 7975376c8c..7975376c8c 100644 --- a/doc/src/images/tcpstream.png +++ b/src/network/doc/images/tcpstream.png diff --git a/doc/src/images/udppackets.png b/src/network/doc/images/udppackets.png Binary files differindex bd66c3f65e..bd66c3f65e 100644 --- a/doc/src/images/udppackets.png +++ b/src/network/doc/images/udppackets.png diff --git a/doc/src/network/network-programming/bearermanagement.qdoc b/src/network/doc/src/bearermanagement.qdoc index 91dc32c5a5..91dc32c5a5 100644 --- a/doc/src/network/network-programming/bearermanagement.qdoc +++ b/src/network/doc/src/bearermanagement.qdoc diff --git a/doc/src/network/network-programming/qtnetwork.qdoc b/src/network/doc/src/network-programming.qdoc index 0701b04f6f..0701b04f6f 100644 --- a/doc/src/network/network-programming/qtnetwork.qdoc +++ b/src/network/doc/src/network-programming.qdoc diff --git a/doc/src/network/network-programming/ssl.qdoc b/src/network/doc/src/ssl.qdoc index 21828d7af9..21828d7af9 100644 --- a/doc/src/network/network-programming/ssl.qdoc +++ b/src/network/doc/src/ssl.qdoc diff --git a/doc/src/images/addressbook-tutorial-part1-labeled-layout.png b/src/widgets/doc/images/addressbook-tutorial-part1-labeled-layout.png Binary files differindex b19cb360a1..b19cb360a1 100644 --- a/doc/src/images/addressbook-tutorial-part1-labeled-layout.png +++ b/src/widgets/doc/images/addressbook-tutorial-part1-labeled-layout.png diff --git a/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part1-labeled-screenshot.png Binary files differindex f9b91eebe6..f9b91eebe6 100644 --- a/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-part1-labeled-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part1-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part1-screenshot.png Binary files differindex 454b0959e6..454b0959e6 100644 --- a/doc/src/images/addressbook-tutorial-part1-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-part1-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part2-add-contact.png b/src/widgets/doc/images/addressbook-tutorial-part2-add-contact.png Binary files differindex 6f2b947b21..6f2b947b21 100644 --- a/doc/src/images/addressbook-tutorial-part2-add-contact.png +++ b/src/widgets/doc/images/addressbook-tutorial-part2-add-contact.png diff --git a/doc/src/images/addressbook-tutorial-part2-add-flowchart.png b/src/widgets/doc/images/addressbook-tutorial-part2-add-flowchart.png Binary files differindex ca9af3720d..ca9af3720d 100644 --- a/doc/src/images/addressbook-tutorial-part2-add-flowchart.png +++ b/src/widgets/doc/images/addressbook-tutorial-part2-add-flowchart.png diff --git a/doc/src/images/addressbook-tutorial-part2-add-successful.png b/src/widgets/doc/images/addressbook-tutorial-part2-add-successful.png Binary files differindex 99a2154007..99a2154007 100644 --- a/doc/src/images/addressbook-tutorial-part2-add-successful.png +++ b/src/widgets/doc/images/addressbook-tutorial-part2-add-successful.png diff --git a/doc/src/images/addressbook-tutorial-part2-labeled-layout.png b/src/widgets/doc/images/addressbook-tutorial-part2-labeled-layout.png Binary files differindex 1e000c8f31..1e000c8f31 100644 --- a/doc/src/images/addressbook-tutorial-part2-labeled-layout.png +++ b/src/widgets/doc/images/addressbook-tutorial-part2-labeled-layout.png diff --git a/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png b/src/widgets/doc/images/addressbook-tutorial-part2-signals-and-slots.png Binary files differindex e49f8dc262..e49f8dc262 100644 --- a/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png +++ b/src/widgets/doc/images/addressbook-tutorial-part2-signals-and-slots.png diff --git a/doc/src/images/addressbook-tutorial-part2-stretch-effects.png b/src/widgets/doc/images/addressbook-tutorial-part2-stretch-effects.png Binary files differindex d9f7f31227..d9f7f31227 100644 --- a/doc/src/images/addressbook-tutorial-part2-stretch-effects.png +++ b/src/widgets/doc/images/addressbook-tutorial-part2-stretch-effects.png diff --git a/doc/src/images/addressbook-tutorial-part3-labeled-layout.png b/src/widgets/doc/images/addressbook-tutorial-part3-labeled-layout.png Binary files differindex 1981ba8cb6..1981ba8cb6 100644 --- a/doc/src/images/addressbook-tutorial-part3-labeled-layout.png +++ b/src/widgets/doc/images/addressbook-tutorial-part3-labeled-layout.png diff --git a/doc/src/images/addressbook-tutorial-part3-linkedlist.png b/src/widgets/doc/images/addressbook-tutorial-part3-linkedlist.png Binary files differindex e7f4725dce..e7f4725dce 100644 --- a/doc/src/images/addressbook-tutorial-part3-linkedlist.png +++ b/src/widgets/doc/images/addressbook-tutorial-part3-linkedlist.png diff --git a/doc/src/images/addressbook-tutorial-part3-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part3-screenshot.png Binary files differindex 75159b4045..75159b4045 100644 --- a/doc/src/images/addressbook-tutorial-part3-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-part3-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part4-remove.png b/src/widgets/doc/images/addressbook-tutorial-part4-remove.png Binary files differindex 8eb259ef02..8eb259ef02 100644 --- a/doc/src/images/addressbook-tutorial-part4-remove.png +++ b/src/widgets/doc/images/addressbook-tutorial-part4-remove.png diff --git a/doc/src/images/addressbook-tutorial-part5-finddialog.png b/src/widgets/doc/images/addressbook-tutorial-part5-finddialog.png Binary files differindex 743d92ef6f..743d92ef6f 100644 --- a/doc/src/images/addressbook-tutorial-part5-finddialog.png +++ b/src/widgets/doc/images/addressbook-tutorial-part5-finddialog.png diff --git a/doc/src/images/addressbook-tutorial-part5-notfound.png b/src/widgets/doc/images/addressbook-tutorial-part5-notfound.png Binary files differindex 2d35766ab5..2d35766ab5 100644 --- a/doc/src/images/addressbook-tutorial-part5-notfound.png +++ b/src/widgets/doc/images/addressbook-tutorial-part5-notfound.png diff --git a/doc/src/images/addressbook-tutorial-part5-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part5-screenshot.png Binary files differindex 3abe2775c2..3abe2775c2 100644 --- a/doc/src/images/addressbook-tutorial-part5-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-part5-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png b/src/widgets/doc/images/addressbook-tutorial-part5-signals-and-slots.png Binary files differindex 1771e7bbbf..1771e7bbbf 100644 --- a/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png +++ b/src/widgets/doc/images/addressbook-tutorial-part5-signals-and-slots.png diff --git a/doc/src/images/addressbook-tutorial-part6-load.png b/src/widgets/doc/images/addressbook-tutorial-part6-load.png Binary files differindex a027a1decb..a027a1decb 100644 --- a/doc/src/images/addressbook-tutorial-part6-load.png +++ b/src/widgets/doc/images/addressbook-tutorial-part6-load.png diff --git a/doc/src/images/addressbook-tutorial-part6-save.png b/src/widgets/doc/images/addressbook-tutorial-part6-save.png Binary files differindex 757feeb9ac..757feeb9ac 100644 --- a/doc/src/images/addressbook-tutorial-part6-save.png +++ b/src/widgets/doc/images/addressbook-tutorial-part6-save.png diff --git a/doc/src/images/addressbook-tutorial-part6-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part6-screenshot.png Binary files differindex 7bb2f749bf..7bb2f749bf 100644 --- a/doc/src/images/addressbook-tutorial-part6-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-part6-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part7-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part7-screenshot.png Binary files differindex 3e7b3ca522..3e7b3ca522 100644 --- a/doc/src/images/addressbook-tutorial-part7-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-part7-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-screenshot.png Binary files differindex 3fba6e849e..3fba6e849e 100644 --- a/doc/src/images/addressbook-tutorial-screenshot.png +++ b/src/widgets/doc/images/addressbook-tutorial-screenshot.png diff --git a/doc/src/images/clock.png b/src/widgets/doc/images/clock.png Binary files differindex c7f6a1b296..c7f6a1b296 100644 --- a/doc/src/images/clock.png +++ b/src/widgets/doc/images/clock.png diff --git a/src/widgets/doc/images/columnview.png b/src/widgets/doc/images/columnview.png Binary files differnew file mode 100644 index 0000000000..127b79531f --- /dev/null +++ b/src/widgets/doc/images/columnview.png diff --git a/doc/src/images/dummy_tree.png b/src/widgets/doc/images/dummy_tree.png Binary files differindex 7373ea60f6..7373ea60f6 100644 --- a/doc/src/images/dummy_tree.png +++ b/src/widgets/doc/images/dummy_tree.png diff --git a/doc/src/images/example_model.png b/src/widgets/doc/images/example_model.png Binary files differindex 4261261c7e..4261261c7e 100644 --- a/doc/src/images/example_model.png +++ b/src/widgets/doc/images/example_model.png diff --git a/doc/src/images/list_table_tree.png b/src/widgets/doc/images/list_table_tree.png Binary files differindex b2daf1f3a5..b2daf1f3a5 100644 --- a/doc/src/images/list_table_tree.png +++ b/src/widgets/doc/images/list_table_tree.png diff --git a/src/widgets/doc/images/listview.png b/src/widgets/doc/images/listview.png Binary files differnew file mode 100755 index 0000000000..fa49c52c62 --- /dev/null +++ b/src/widgets/doc/images/listview.png diff --git a/doc/src/images/mainwindow-docks-example.png b/src/widgets/doc/images/mainwindow-docks-example.png Binary files differindex a5641fd9cd..a5641fd9cd 100644 --- a/doc/src/images/mainwindow-docks-example.png +++ b/src/widgets/doc/images/mainwindow-docks-example.png diff --git a/src/widgets/doc/images/modelview-combobox.png b/src/widgets/doc/images/modelview-combobox.png Binary files differnew file mode 100755 index 0000000000..d172b413eb --- /dev/null +++ b/src/widgets/doc/images/modelview-combobox.png diff --git a/doc/src/images/modelview-header.png b/src/widgets/doc/images/modelview-header.png Binary files differindex 2597635b9f..2597635b9f 100644 --- a/doc/src/images/modelview-header.png +++ b/src/widgets/doc/images/modelview-header.png diff --git a/src/widgets/doc/images/modelview-models.png b/src/widgets/doc/images/modelview-models.png Binary files differnew file mode 100644 index 0000000000..183a7cffd5 --- /dev/null +++ b/src/widgets/doc/images/modelview-models.png diff --git a/src/widgets/doc/images/modelview-overview.png b/src/widgets/doc/images/modelview-overview.png Binary files differnew file mode 100644 index 0000000000..41e3a6827f --- /dev/null +++ b/src/widgets/doc/images/modelview-overview.png diff --git a/src/widgets/doc/images/modelview-roles.png b/src/widgets/doc/images/modelview-roles.png Binary files differnew file mode 100644 index 0000000000..2a60ce7190 --- /dev/null +++ b/src/widgets/doc/images/modelview-roles.png diff --git a/src/widgets/doc/images/modelview-tablemodel.png b/src/widgets/doc/images/modelview-tablemodel.png Binary files differnew file mode 100644 index 0000000000..9a9ea2f1b0 --- /dev/null +++ b/src/widgets/doc/images/modelview-tablemodel.png diff --git a/src/widgets/doc/images/modelview-treemodel.png b/src/widgets/doc/images/modelview-treemodel.png Binary files differnew file mode 100644 index 0000000000..f7b02eb150 --- /dev/null +++ b/src/widgets/doc/images/modelview-treemodel.png diff --git a/doc/src/images/modelview.png b/src/widgets/doc/images/modelview.png Binary files differindex 7b042af8a4..7b042af8a4 100644 --- a/doc/src/images/modelview.png +++ b/src/widgets/doc/images/modelview.png diff --git a/doc/src/images/qcompleter.png b/src/widgets/doc/images/qcompleter.png Binary files differindex d25caacc72..d25caacc72 100644 --- a/doc/src/images/qcompleter.png +++ b/src/widgets/doc/images/qcompleter.png diff --git a/doc/src/images/readonlytable_role.png b/src/widgets/doc/images/readonlytable_role.png Binary files differindex 7d2d416a53..7d2d416a53 100644 --- a/doc/src/images/readonlytable_role.png +++ b/src/widgets/doc/images/readonlytable_role.png diff --git a/src/widgets/doc/images/selected-items1.png b/src/widgets/doc/images/selected-items1.png Binary files differnew file mode 100644 index 0000000000..12b572d4d8 --- /dev/null +++ b/src/widgets/doc/images/selected-items1.png diff --git a/src/widgets/doc/images/selected-items2.png b/src/widgets/doc/images/selected-items2.png Binary files differnew file mode 100644 index 0000000000..ad247d90a9 --- /dev/null +++ b/src/widgets/doc/images/selected-items2.png diff --git a/src/widgets/doc/images/selected-items3.png b/src/widgets/doc/images/selected-items3.png Binary files differnew file mode 100644 index 0000000000..d7aa7be46b --- /dev/null +++ b/src/widgets/doc/images/selected-items3.png diff --git a/src/widgets/doc/images/selection-extended.png b/src/widgets/doc/images/selection-extended.png Binary files differnew file mode 100644 index 0000000000..8ca488d812 --- /dev/null +++ b/src/widgets/doc/images/selection-extended.png diff --git a/src/widgets/doc/images/selection-multi.png b/src/widgets/doc/images/selection-multi.png Binary files differnew file mode 100644 index 0000000000..766e4a18bc --- /dev/null +++ b/src/widgets/doc/images/selection-multi.png diff --git a/src/widgets/doc/images/selection-single.png b/src/widgets/doc/images/selection-single.png Binary files differnew file mode 100644 index 0000000000..d9d0655864 --- /dev/null +++ b/src/widgets/doc/images/selection-single.png diff --git a/doc/src/images/selection2.png b/src/widgets/doc/images/selection2.png Binary files differindex 66c757f88e..66c757f88e 100644 --- a/doc/src/images/selection2.png +++ b/src/widgets/doc/images/selection2.png diff --git a/src/widgets/doc/images/shareddirmodel.png b/src/widgets/doc/images/shareddirmodel.png Binary files differnew file mode 100644 index 0000000000..7b9fdeda04 --- /dev/null +++ b/src/widgets/doc/images/shareddirmodel.png diff --git a/src/widgets/doc/images/sharedmodel-tableviews.png b/src/widgets/doc/images/sharedmodel-tableviews.png Binary files differnew file mode 100644 index 0000000000..d241e4ca1a --- /dev/null +++ b/src/widgets/doc/images/sharedmodel-tableviews.png diff --git a/src/widgets/doc/images/sharedselection-tableviews.png b/src/widgets/doc/images/sharedselection-tableviews.png Binary files differnew file mode 100644 index 0000000000..ccbda2578f --- /dev/null +++ b/src/widgets/doc/images/sharedselection-tableviews.png diff --git a/doc/src/images/spinboxdelegate-example.png b/src/widgets/doc/images/spinboxdelegate-example.png Binary files differindex 5e57a9c12b..5e57a9c12b 100644 --- a/doc/src/images/spinboxdelegate-example.png +++ b/src/widgets/doc/images/spinboxdelegate-example.png diff --git a/src/widgets/doc/images/standard-views.png b/src/widgets/doc/images/standard-views.png Binary files differnew file mode 100644 index 0000000000..c804551622 --- /dev/null +++ b/src/widgets/doc/images/standard-views.png diff --git a/doc/src/images/standardwidget.png b/src/widgets/doc/images/standardwidget.png Binary files differindex 3ccccf14a3..3ccccf14a3 100644 --- a/doc/src/images/standardwidget.png +++ b/src/widgets/doc/images/standardwidget.png diff --git a/doc/src/images/stardelegate.png b/src/widgets/doc/images/stardelegate.png Binary files differindex 24fa9fb0d7..24fa9fb0d7 100644 --- a/doc/src/images/stardelegate.png +++ b/src/widgets/doc/images/stardelegate.png diff --git a/src/widgets/doc/images/stringlistmodel.png b/src/widgets/doc/images/stringlistmodel.png Binary files differnew file mode 100644 index 0000000000..eedbff3585 --- /dev/null +++ b/src/widgets/doc/images/stringlistmodel.png diff --git a/src/widgets/doc/images/tableview.png b/src/widgets/doc/images/tableview.png Binary files differnew file mode 100755 index 0000000000..8be1b6ce62 --- /dev/null +++ b/src/widgets/doc/images/tableview.png diff --git a/doc/src/images/tree_2_with_algorithm.png b/src/widgets/doc/images/tree_2_with_algorithm.png Binary files differindex ecf91012bf..ecf91012bf 100644 --- a/doc/src/images/tree_2_with_algorithm.png +++ b/src/widgets/doc/images/tree_2_with_algorithm.png diff --git a/doc/src/images/treeview.png b/src/widgets/doc/images/treeview.png Binary files differindex af31fe9bf1..af31fe9bf1 100644 --- a/doc/src/images/treeview.png +++ b/src/widgets/doc/images/treeview.png diff --git a/doc/src/images/widgetmapper.png b/src/widgets/doc/images/widgetmapper.png Binary files differindex 9627088077..9627088077 100644 --- a/doc/src/images/widgetmapper.png +++ b/src/widgets/doc/images/widgetmapper.png diff --git a/src/widgets/doc/images/widgets-tutorial-childwidget.png b/src/widgets/doc/images/widgets-tutorial-childwidget.png Binary files differnew file mode 100644 index 0000000000..0d42d701fc --- /dev/null +++ b/src/widgets/doc/images/widgets-tutorial-childwidget.png diff --git a/src/widgets/doc/images/widgets-tutorial-nestedlayouts.png b/src/widgets/doc/images/widgets-tutorial-nestedlayouts.png Binary files differnew file mode 100644 index 0000000000..1e2a9f4a1d --- /dev/null +++ b/src/widgets/doc/images/widgets-tutorial-nestedlayouts.png diff --git a/src/widgets/doc/images/widgets-tutorial-toplevel.png b/src/widgets/doc/images/widgets-tutorial-toplevel.png Binary files differnew file mode 100644 index 0000000000..a80d13c50d --- /dev/null +++ b/src/widgets/doc/images/widgets-tutorial-toplevel.png diff --git a/src/widgets/doc/images/widgets-tutorial-windowlayout.png b/src/widgets/doc/images/widgets-tutorial-windowlayout.png Binary files differnew file mode 100644 index 0000000000..fce52cdcd9 --- /dev/null +++ b/src/widgets/doc/images/widgets-tutorial-windowlayout.png diff --git a/doc/src/snippets/code/src_gui_embedded_qcopchannel_qws.cpp b/src/widgets/doc/snippets/code/doc_src_model-view-programming.cpp index 76b958dda3..ca9aa606f7 100644 --- a/doc/src/snippets/code/src_gui_embedded_qcopchannel_qws.cpp +++ b/src/widgets/doc/snippets/code/doc_src_model-view-programming.cpp @@ -39,28 +39,38 @@ ****************************************************************************/ //! [0] -void MyClass::receive(const QString &message, const QByteArray &data) -{ - QDataStream in(data); - if (message == "execute(QString,QString)") { - QString cmd; - QString arg; - in >> cmd >> arg; - ... - } else if (message == "delete(QString)") { - QString fileName; - in >> fileName; - ... - } else { - ... - } -} +QAbstractItemModel *model = index.model(); //! [0] //! [1] -QByteArray data; -QDataStream out(&data, QIODevice::WriteOnly); -out << QString("cat") << QString("file.txt"); -QCopChannel::send("System/Shell", "execute(QString,QString)", data); +QModelIndex index = model->index(row, column, ...); //! [1] + + +//! [2] +QModelIndex indexA = model->index(0, 0, QModelIndex()); +QModelIndex indexB = model->index(1, 1, QModelIndex()); +QModelIndex indexC = model->index(2, 1, QModelIndex()); +//! [2] + + +//! [3] +QModelIndex index = model->index(row, column, parent); +//! [3] + + +//! [4] +QModelIndex indexA = model->index(0, 0, QModelIndex()); +QModelIndex indexC = model->index(2, 1, QModelIndex()); +//! [4] + + +//! [5] +QModelIndex indexB = model->index(1, 0, indexA); +//! [5] + + +//! [6] +QVariant value = model->data(index, role); +//! [6] diff --git a/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp b/src/widgets/doc/snippets/code/doc_src_qt4-mainwindow.cpp index ecbb5f5220..ecbb5f5220 100644 --- a/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp +++ b/src/widgets/doc/snippets/code/doc_src_qt4-mainwindow.cpp diff --git a/doc/src/snippets/dockwidgets/mainwindow.cpp b/src/widgets/doc/snippets/dockwidgets/mainwindow.cpp index 882af70b64..882af70b64 100644 --- a/doc/src/snippets/dockwidgets/mainwindow.cpp +++ b/src/widgets/doc/snippets/dockwidgets/mainwindow.cpp diff --git a/src/widgets/doc/snippets/itemselection/itemselection.pro b/src/widgets/doc/snippets/itemselection/itemselection.pro new file mode 100644 index 0000000000..b1126bfe73 --- /dev/null +++ b/src/widgets/doc/snippets/itemselection/itemselection.pro @@ -0,0 +1,3 @@ +HEADERS = model.h +SOURCES = main.cpp \ + model.cpp diff --git a/src/widgets/doc/snippets/itemselection/main.cpp b/src/widgets/doc/snippets/itemselection/main.cpp new file mode 100644 index 0000000000..f39fb68b32 --- /dev/null +++ b/src/widgets/doc/snippets/itemselection/main.cpp @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + main.cpp + + A simple example that shows how selections can be used directly on a model. + It shows the result of some selections made using a table view. +*/ + +#include <QApplication> +#include <QItemSelection> +#include <QItemSelectionModel> +#include <QTableView> + +#include "model.h" + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + +//! [0] + TableModel *model = new TableModel(8, 4, &app); + + QTableView *table = new QTableView(0); + table->setModel(model); + + QItemSelectionModel *selectionModel = table->selectionModel(); +//! [0] //! [1] + QModelIndex topLeft; + QModelIndex bottomRight; + + topLeft = model->index(0, 0, QModelIndex()); + bottomRight = model->index(5, 2, QModelIndex()); +//! [1] + +//! [2] + QItemSelection selection(topLeft, bottomRight); + selectionModel->select(selection, QItemSelectionModel::Select); +//! [2] + +//! [3] + QItemSelection toggleSelection; + + topLeft = model->index(2, 1, QModelIndex()); + bottomRight = model->index(7, 3, QModelIndex()); + toggleSelection.select(topLeft, bottomRight); + + selectionModel->select(toggleSelection, QItemSelectionModel::Toggle); +//! [3] + +//! [4] + QItemSelection columnSelection; + + topLeft = model->index(0, 1, QModelIndex()); + bottomRight = model->index(0, 2, QModelIndex()); + + columnSelection.select(topLeft, bottomRight); + + selectionModel->select(columnSelection, + QItemSelectionModel::Select | QItemSelectionModel::Columns); + + QItemSelection rowSelection; + + topLeft = model->index(0, 0, QModelIndex()); + bottomRight = model->index(1, 0, QModelIndex()); + + rowSelection.select(topLeft, bottomRight); + + selectionModel->select(rowSelection, + QItemSelectionModel::Select | QItemSelectionModel::Rows); +//! [4] + + table->setWindowTitle("Selected items in a table model"); + table->show(); + table->resize(460, 280); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/itemselection/model.cpp b/src/widgets/doc/snippets/itemselection/model.cpp new file mode 100644 index 0000000000..6c9c5bad82 --- /dev/null +++ b/src/widgets/doc/snippets/itemselection/model.cpp @@ -0,0 +1,238 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + model.cpp + + Provides a table model for use in various examples. +*/ + +#include <QtGui> + +#include "model.h" + +/*! + Constructs a table model with at least one row and one column. +*/ + +TableModel::TableModel(int rows, int columns, QObject *parent) + : QAbstractTableModel(parent) +{ + QStringList newList; + + for (int column = 0; column < qMax(1, columns); ++column) { + newList.append(""); + } + + for (int row = 0; row < qMax(1, rows); ++row) { + rowList.append(newList); + } +} + + +/*! + Returns the number of items in the row list as the number of rows + in the model. +*/ + +int TableModel::rowCount(const QModelIndex &/*parent*/) const +{ + return rowList.size(); +} + +/*! + Returns the number of items in the first list item as the number of + columns in the model. All rows should have the same number of columns. +*/ + +int TableModel::columnCount(const QModelIndex &/*parent*/) const +{ + return rowList[0].size(); +} + +/*! + Returns an appropriate value for the requested data. + If the view requests an invalid index, an invalid variant is returned. + Any valid index that corresponds to a string in the list causes that + string to be returned for the display role; otherwise an invalid variant + is returned. +*/ + +QVariant TableModel::data(const QModelIndex &index, int role) const +{ + if (!index.isValid()) + return QVariant(); + + if (role == Qt::DisplayRole) + return rowList[index.row()][index.column()]; + else + return QVariant(); +} + +/*! + Returns the appropriate header string depending on the orientation of + the header and the section. If anything other than the display role is + requested, we return an invalid variant. +*/ + +QVariant TableModel::headerData(int section, Qt::Orientation orientation, + int role) const +{ + if (role != Qt::DisplayRole) + return QVariant(); + + if (orientation == Qt::Horizontal) + return QString("Column %1").arg(section); + else + return QString("Row %1").arg(section); +} + +/*! + Returns an appropriate value for the item's flags. Valid items are + enabled, selectable, and editable. +*/ + +Qt::ItemFlags TableModel::flags(const QModelIndex &index) const +{ + if (!index.isValid()) + return Qt::ItemIsEnabled; + + return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable; +} + +/*! + Changes an item in the model, but only if the following conditions + are met: + + * The index supplied is valid. + * The role associated with editing text is specified. + + The dataChanged() signal is emitted if the item is changed. +*/ + +bool TableModel::setData(const QModelIndex &index, + const QVariant &value, int role) +{ + if (!index.isValid() || role != Qt::EditRole) + return false; + + rowList[index.row()][index.column()] = value.toString(); + emit dataChanged(index, index); + return true; +} + +/*! + Inserts a number of rows into the model at the specified position. +*/ + +bool TableModel::insertRows(int position, int rows, const QModelIndex &parent) +{ + int columns = columnCount(); + beginInsertRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + QStringList items; + for (int column = 0; column < columns; ++column) + items.append(""); + rowList.insert(position, items); + } + + endInsertRows(); + return true; +} + +/*! + Inserts a number of columns into the model at the specified position. + Each entry in the list is extended in turn with the required number of + empty strings. +*/ + +bool TableModel::insertColumns(int position, int columns, + const QModelIndex &parent) +{ + int rows = rowCount(); + beginInsertColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = position; column < columns; ++column) { + rowList[row].insert(position, ""); + } + } + + endInsertColumns(); + return true; +} + +/*! + Removes a number of rows from the model at the specified position. +*/ + +bool TableModel::removeRows(int position, int rows, const QModelIndex &parent) +{ + beginRemoveRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + rowList.removeAt(position); + } + + endRemoveRows(); + return true; +} + +/*! + Removes a number of columns from the model at the specified position. + Each row is shortened by the number of columns specified. +*/ + +bool TableModel::removeColumns(int position, int columns, + const QModelIndex &parent) +{ + int rows = rowCount(); + beginRemoveColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = 0; column < columns; ++column) { + rowList[row].removeAt(position); + } + } + + endRemoveColumns(); + return true; +} diff --git a/src/widgets/doc/snippets/itemselection/model.h b/src/widgets/doc/snippets/itemselection/model.h new file mode 100644 index 0000000000..ef63e45ce0 --- /dev/null +++ b/src/widgets/doc/snippets/itemselection/model.h @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 MODEL_H +#define MODEL_H + +#include <QAbstractTableModel> +#include <QStringList> +#include <QVariant> + +class TableModel : public QAbstractTableModel +{ + Q_OBJECT + +public: + TableModel(int rows = 1, int columns = 1, QObject *parent = 0); + + int rowCount(const QModelIndex &parent = QModelIndex()) const; + int columnCount(const QModelIndex &parent = QModelIndex()) const; + QVariant data(const QModelIndex &index, int role) const; + QVariant headerData(int section, Qt::Orientation orientation, + int role = Qt::DisplayRole) const; + + Qt::ItemFlags flags(const QModelIndex &index) const; + bool setData(const QModelIndex &index, const QVariant &value, + int role = Qt::EditRole); + + bool insertRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool insertColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + bool removeRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool removeColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + +private: + QList<QStringList> rowList; +}; + +#endif diff --git a/doc/src/snippets/code/src_gui_embedded_qscreen_qws.cpp b/src/widgets/doc/snippets/qlistview-dnd/main.cpp index 99be26133e..56bff2a612 100644 --- a/doc/src/snippets/code/src_gui_embedded_qscreen_qws.cpp +++ b/src/widgets/doc/snippets/qlistview-dnd/main.cpp @@ -38,11 +38,14 @@ ** ****************************************************************************/ -//! [0] -[screen driver][:driver specific options][:display number] -//! [0] +#include <QtGui> +#include "mainwindow.h" -//! [1] -Mach64:/dev/fb1:2 -//! [1] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MainWindow *window = new MainWindow; + window->show(); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/qlistview-dnd/mainwindow.cpp b/src/widgets/doc/snippets/qlistview-dnd/mainwindow.cpp new file mode 100644 index 0000000000..ff35c5e25d --- /dev/null +++ b/src/widgets/doc/snippets/qlistview-dnd/mainwindow.cpp @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" +#include "model.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + menuBar()->addMenu(fileMenu); + +// For convenient quoting: +//! [0] +QListView *listView = new QListView(this); +listView->setSelectionMode(QAbstractItemView::ExtendedSelection); +listView->setDragEnabled(true); +listView->setAcceptDrops(true); +listView->setDropIndicatorShown(true); +//! [0] + + this->listView = listView; + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + + setupListItems(); + + setCentralWidget(listView); + setWindowTitle(tr("List View")); +} + +void MainWindow::setupListItems() +{ + QStringList items; + items << tr("Oak") << tr("Fir") << tr("Pine") << tr("Birch") << tr("Hazel") + << tr("Redwood") << tr("Sycamore") << tr("Chestnut") + << tr("Mahogany"); + + DragDropListModel *model = new DragDropListModel(items, this); + listView->setModel(model); +} diff --git a/doc/src/snippets/code/src_gui_embedded_qmouse_qws.cpp b/src/widgets/doc/snippets/qlistview-dnd/mainwindow.h index 8fc6140075..daac61260e 100644 --- a/doc/src/snippets/code/src_gui_embedded_qmouse_qws.cpp +++ b/src/widgets/doc/snippets/qlistview-dnd/mainwindow.h @@ -38,7 +38,24 @@ ** ****************************************************************************/ -//! [0] -s*Xs = a*Xd + b*Yd + c -s*Ys = d*Xd + e*Yd + f -//! [0] +#ifndef WINDOW_H +#define WINDOW_H + +#include <QMainWindow> + +class QListView; + +class MainWindow : public QMainWindow +{ + Q_OBJECT + +public: + MainWindow(); + +private: + void setupListItems(); + + QListView *listView; +}; + +#endif diff --git a/src/widgets/doc/snippets/qlistview-dnd/model.cpp b/src/widgets/doc/snippets/qlistview-dnd/model.cpp new file mode 100644 index 0000000000..190ac968c0 --- /dev/null +++ b/src/widgets/doc/snippets/qlistview-dnd/model.cpp @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of an example program for Qt. +** EDITIONS: NOLIMITS +** +****************************************************************************/ + +/* + model.cpp + + A simple model that uses a QStringList as its data source. +*/ + +#include <QtGui> + +#include "model.h" + +DragDropListModel::DragDropListModel(const QStringList &strings, + QObject *parent) + : QStringListModel(strings, parent) +{ +} + +//! [0] +bool DragDropListModel::dropMimeData(const QMimeData *data, + Qt::DropAction action, int row, int column, const QModelIndex &parent) +{ + if (action == Qt::IgnoreAction) + return true; + + if (!data->hasFormat("application/vnd.text.list")) + return false; + + if (column > 0) +//! [0] //! [1] + return false; +//! [1] + +//! [2] + int beginRow; + + if (row != -1) + beginRow = row; +//! [2] //! [3] + else if (parent.isValid()) + beginRow = parent.row(); +//! [3] //! [4] + else + beginRow = rowCount(QModelIndex()); +//! [4] + +//! [5] + QByteArray encodedData = data->data("application/vnd.text.list"); + QDataStream stream(&encodedData, QIODevice::ReadOnly); + QStringList newItems; + int rows = 0; + + while (!stream.atEnd()) { + QString text; + stream >> text; + newItems << text; + ++rows; + } +//! [5] + +//! [6] + insertRows(beginRow, rows, QModelIndex()); + foreach (const QString &text, newItems) { + QModelIndex idx = index(beginRow, 0, QModelIndex()); + setData(idx, text); + beginRow++; + } + + return true; +} +//! [6] + +//! [7] +Qt::ItemFlags DragDropListModel::flags(const QModelIndex &index) const +{ + Qt::ItemFlags defaultFlags = QStringListModel::flags(index); + + if (index.isValid()) + return Qt::ItemIsDragEnabled | Qt::ItemIsDropEnabled | defaultFlags; + else + return Qt::ItemIsDropEnabled | defaultFlags; +} +//! [7] + +//! [8] +QMimeData *DragDropListModel::mimeData(const QModelIndexList &indexes) const +{ + QMimeData *mimeData = new QMimeData(); + QByteArray encodedData; + + QDataStream stream(&encodedData, QIODevice::WriteOnly); + + foreach (const QModelIndex &index, indexes) { + if (index.isValid()) { + QString text = data(index, Qt::DisplayRole).toString(); + stream << text; + } + } + + mimeData->setData("application/vnd.text.list", encodedData); + return mimeData; +} +//! [8] + +//! [9] +QStringList DragDropListModel::mimeTypes() const +{ + QStringList types; + types << "application/vnd.text.list"; + return types; +} +//! [9] + +//! [10] +Qt::DropActions DragDropListModel::supportedDropActions() const +{ + return Qt::CopyAction | Qt::MoveAction; +} +//! [10] diff --git a/doc/src/snippets/code/src_gui_embedded_qtransportauth_qws.cpp b/src/widgets/doc/snippets/qlistview-dnd/model.h index e73ee2ed0a..9d1ff904e1 100644 --- a/doc/src/snippets/code/src_gui_embedded_qtransportauth_qws.cpp +++ b/src/widgets/doc/snippets/qlistview-dnd/model.h @@ -38,50 +38,36 @@ ** ****************************************************************************/ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of an example program for Qt. +** EDITIONS: NOLIMITS +** +****************************************************************************/ -void wrapInFunction() -{ - -//! [0] -QTransportAuth::Data *conData; -QTransportAuth *a = QTransportAuth::getInstance(); - -conData = a->connectTransport( - QTransportAuth::Trusted | QTransportAuth::UnixStreamSock, - socketDescriptor ); -//! [0] - - -//! [1] -// mySocket can be any QIODevice subclass -AuthDevice *ad = a->recvBuf( d, mySocket ); - -// proxy in the auth device where the socket would have gone -connect( ad, SIGNAL(readyRead()), this, SLOT(mySocketReadyRead())); -//! [1] - - -//! [2] -AuthDevice *ad = a->authBuf( d, mySocket ); - -ad->write( someData ); -//! [2] - - -//! [3] -policyCheck( QTransportAuth::Data &, const QString & ) -//! [3] +#ifndef MODEL_H +#define MODEL_H +#include <QObject> +#include <QStringListModel> -//! [4] -QTransportAuth::Result r = d.status & QTransportAuth::ErrMask; -qWarning( "error: %s", QTransportAuth::errorStrings[r] ); -//! [4] +class DragDropListModel : public QStringListModel +{ + Q_OBJECT +public: + DragDropListModel(const QStringList &strings, QObject *parent = 0); -//! [5] -MD5(K XOR opad, MD5(K XOR ipad, text)) -//! [5] + Qt::ItemFlags flags(const QModelIndex &index) const; -} + bool dropMimeData(const QMimeData *data, Qt::DropAction action, + int row, int column, const QModelIndex &parent); + QMimeData *mimeData(const QModelIndexList &indexes) const; + QStringList mimeTypes() const; + Qt::DropActions supportedDropActions() const; +}; +#endif diff --git a/src/widgets/doc/snippets/qlistview-dnd/qlistview-dnd.pro b/src/widgets/doc/snippets/qlistview-dnd/qlistview-dnd.pro new file mode 100644 index 0000000000..71fa273a69 --- /dev/null +++ b/src/widgets/doc/snippets/qlistview-dnd/qlistview-dnd.pro @@ -0,0 +1,5 @@ +SOURCES = main.cpp \ + mainwindow.cpp \ + model.cpp +HEADERS = mainwindow.h \ + model.h diff --git a/doc/src/snippets/code/src_gui_embedded_qmousetslib_qws.cpp b/src/widgets/doc/snippets/qlistwidget-dnd/main.cpp index 7a2eee142e..56bff2a612 100644 --- a/doc/src/snippets/code/src_gui_embedded_qmousetslib_qws.cpp +++ b/src/widgets/doc/snippets/qlistwidget-dnd/main.cpp @@ -38,12 +38,14 @@ ** ****************************************************************************/ -//! [0] -configure -L <path to tslib library> -I <path to tslib headers> -//! [0] +#include <QtGui> +#include "mainwindow.h" -//! [1] -module_raw input -module linear -//! [1] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MainWindow *window = new MainWindow; + window->show(); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/qlistwidget-dnd/mainwindow.cpp b/src/widgets/doc/snippets/qlistwidget-dnd/mainwindow.cpp new file mode 100644 index 0000000000..8d93f823f4 --- /dev/null +++ b/src/widgets/doc/snippets/qlistwidget-dnd/mainwindow.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + menuBar()->addMenu(fileMenu); + +// For convenient quoting: +//! [0] +QListWidget *listWidget = new QListWidget(this); +listWidget->setSelectionMode(QAbstractItemView::SingleSelection); +listWidget->setDragEnabled(true); +listWidget->viewport()->setAcceptDrops(true); +listWidget->setDropIndicatorShown(true); +//! [0] //! [1] +listWidget->setDragDropMode(QAbstractItemView::InternalMove); +//! [1] + + this->listWidget = listWidget; + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + + setupListItems(); + + setCentralWidget(listWidget); + setWindowTitle(tr("List Widget")); +} + +void MainWindow::setupListItems() +{ + QListWidgetItem *item; + item = new QListWidgetItem(tr("Oak"), listWidget); + item = new QListWidgetItem(tr("Fir"), listWidget); + item = new QListWidgetItem(tr("Pine"), listWidget); + item = new QListWidgetItem(tr("Birch"), listWidget); + item = new QListWidgetItem(tr("Hazel"), listWidget); + item = new QListWidgetItem(tr("Redwood"), listWidget); + item = new QListWidgetItem(tr("Sycamore"), listWidget); + item = new QListWidgetItem(tr("Chestnut"), listWidget); + item = new QListWidgetItem(tr("Mahogany"), listWidget); +} diff --git a/src/widgets/doc/snippets/qlistwidget-dnd/mainwindow.h b/src/widgets/doc/snippets/qlistwidget-dnd/mainwindow.h new file mode 100644 index 0000000000..50cac647d1 --- /dev/null +++ b/src/widgets/doc/snippets/qlistwidget-dnd/mainwindow.h @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 WINDOW_H +#define WINDOW_H + +#include <QMainWindow> + +class QListWidget; +class QListWidgetItem; + +class MainWindow : public QMainWindow +{ + Q_OBJECT + +public: + MainWindow(); + +private: + void setupListItems(); + + QListWidget *listWidget; +}; + +#endif diff --git a/src/widgets/doc/snippets/qlistwidget-dnd/qlistwidget-dnd.pro b/src/widgets/doc/snippets/qlistwidget-dnd/qlistwidget-dnd.pro new file mode 100644 index 0000000000..12a900a7c6 --- /dev/null +++ b/src/widgets/doc/snippets/qlistwidget-dnd/qlistwidget-dnd.pro @@ -0,0 +1,3 @@ +SOURCES = main.cpp \ + mainwindow.cpp +HEADERS = mainwindow.h diff --git a/src/widgets/doc/snippets/qsortfilterproxymodel/main.cpp b/src/widgets/doc/snippets/qsortfilterproxymodel/main.cpp new file mode 100644 index 0000000000..0d78ae3f10 --- /dev/null +++ b/src/widgets/doc/snippets/qsortfilterproxymodel/main.cpp @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QObject *parent = &app; + + QStringList numbers; + numbers << "One" << "Two" << "Three" << "Four" << "Five"; + + QAbstractItemModel *stringListModel = new QStringListModel(numbers, parent); + +//! [0] + QSortFilterProxyModel *filterModel = new QSortFilterProxyModel(parent); + filterModel->setSourceModel(stringListModel); +//! [0] + + QWidget *window = new QWidget; + +//! [1] + QListView *filteredView = new QListView; + filteredView->setModel(filterModel); +//! [1] + filteredView->setWindowTitle("Filtered view onto a string list model"); + + QLineEdit *patternEditor = new QLineEdit; + QObject:: + connect(patternEditor, SIGNAL(textChanged(const QString &)), + filterModel, SLOT(setFilterRegExp(const QString &))); + + QVBoxLayout *layout = new QVBoxLayout(window); + layout->addWidget(filteredView); + layout->addWidget(patternEditor); + + window->show(); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/qsortfilterproxymodel/qsortfilterproxymodel.pro b/src/widgets/doc/snippets/qsortfilterproxymodel/qsortfilterproxymodel.pro new file mode 100644 index 0000000000..16181f21cf --- /dev/null +++ b/src/widgets/doc/snippets/qsortfilterproxymodel/qsortfilterproxymodel.pro @@ -0,0 +1 @@ +SOURCES = main.cpp diff --git a/src/widgets/doc/snippets/qtablewidget-using/Images/cubed.png b/src/widgets/doc/snippets/qtablewidget-using/Images/cubed.png Binary files differnew file mode 100644 index 0000000000..2cd9048ca6 --- /dev/null +++ b/src/widgets/doc/snippets/qtablewidget-using/Images/cubed.png diff --git a/src/widgets/doc/snippets/qtablewidget-using/Images/squared.png b/src/widgets/doc/snippets/qtablewidget-using/Images/squared.png Binary files differnew file mode 100644 index 0000000000..bfdf993289 --- /dev/null +++ b/src/widgets/doc/snippets/qtablewidget-using/Images/squared.png diff --git a/src/widgets/doc/snippets/qtablewidget-using/images.qrc b/src/widgets/doc/snippets/qtablewidget-using/images.qrc new file mode 100644 index 0000000000..1d49b52866 --- /dev/null +++ b/src/widgets/doc/snippets/qtablewidget-using/images.qrc @@ -0,0 +1,6 @@ +<!DOCTYPE RCC><RCC version="1.0"> +<qresource> + <file>Images/squared.png</file> + <file>Images/cubed.png</file> +</qresource> +</RCC> diff --git a/src/widgets/doc/snippets/qtablewidget-using/main.cpp b/src/widgets/doc/snippets/qtablewidget-using/main.cpp new file mode 100644 index 0000000000..56bff2a612 --- /dev/null +++ b/src/widgets/doc/snippets/qtablewidget-using/main.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MainWindow *window = new MainWindow; + window->show(); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/qtablewidget-using/mainwindow.h b/src/widgets/doc/snippets/qtablewidget-using/mainwindow.h new file mode 100644 index 0000000000..5c8c997762 --- /dev/null +++ b/src/widgets/doc/snippets/qtablewidget-using/mainwindow.h @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 WINDOW_H +#define WINDOW_H + +#include <QMainWindow> + +class QAction; +class QTableWidget; +class QTableWidgetItem; + +class MainWindow : public QMainWindow +{ + Q_OBJECT + +public: + MainWindow(); + +public slots: + void averageItems(); + void sumItems(); + +private: + void setupTableItems(); + + QAction *removeAction; +//! [0] + QTableWidget *tableWidget; +//! [0] +}; + +#endif diff --git a/src/widgets/doc/snippets/qtablewidget-using/qtablewidget-using.pro b/src/widgets/doc/snippets/qtablewidget-using/qtablewidget-using.pro new file mode 100644 index 0000000000..ffe134cbb6 --- /dev/null +++ b/src/widgets/doc/snippets/qtablewidget-using/qtablewidget-using.pro @@ -0,0 +1,4 @@ +SOURCES = main.cpp \ + mainwindow.cpp +HEADERS = mainwindow.h +RESOURCES += images.qrc diff --git a/src/widgets/doc/snippets/reading-selections/main.cpp b/src/widgets/doc/snippets/reading-selections/main.cpp new file mode 100644 index 0000000000..3356ffc8ab --- /dev/null +++ b/src/widgets/doc/snippets/reading-selections/main.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + main.cpp + + A simple example that shows how selections can be used directly on a model. + It shows the result of some selections made using a table view. +*/ + +#include <QApplication> + +#include "window.h" + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QMainWindow *window = new MainWindow; + window->show(); + window->resize(640, 480); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/reading-selections/model.cpp b/src/widgets/doc/snippets/reading-selections/model.cpp new file mode 100644 index 0000000000..ca4b9f84dd --- /dev/null +++ b/src/widgets/doc/snippets/reading-selections/model.cpp @@ -0,0 +1,238 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + model.cpp + + Provides a table model for use in various examples. +*/ + +#include <QtGui> + +#include "model.h" + +/*! + Constructs a table model with at least one row and one column. +*/ + +TableModel::TableModel(int rows, int columns, QObject *parent) + : QAbstractTableModel(parent) +{ + QStringList newList; + + for (int column = 0; column < qMax(1, columns); ++column) { + newList.append(""); + } + + for (int row = 0; row < qMax(1, rows); ++row) { + rowList.append(newList); + } +} + + +/*! + Returns the number of items in the row list as the number of rows + in the model. +*/ + +int TableModel::rowCount(const QModelIndex &/*parent*/) const +{ + return rowList.size(); +} + +/*! + Returns the number of items in the first list item as the number of + columns in the model. All rows should have the same number of columns. +*/ + +int TableModel::columnCount(const QModelIndex &/*parent*/) const +{ + return rowList[0].size(); +} + +/*! + Returns an appropriate value for the requested data. + If the view requests an invalid index, an invalid variant is returned. + Any valid index that corresponds to a string in the list causes that + string to be returned for the display role; otherwise an invalid variant + is returned. +*/ + +QVariant TableModel::data(const QModelIndex &index, int role) const +{ + if (!index.isValid()) + return QVariant(); + + if (role == Qt::DisplayRole) + return rowList[index.row()][index.column()]; + else + return QVariant(); +} + +/*! + Returns the appropriate header string depending on the orientation of + the header and the section. If anything other than the display role is + requested, we return an invalid variant. +*/ + +QVariant TableModel::headerData(int section, Qt::Orientation orientation, + int role) const +{ + if (role != Qt::DisplayRole) + return QVariant(); + + if (orientation == Qt::Horizontal) + return QString("Column %1").arg(section); + else + return QString("Row %1").arg(section); +} + +/*! + Returns an appropriate value for the item's flags. Valid items are + enabled, selectable, and editable. +*/ + +Qt::ItemFlags TableModel::flags(const QModelIndex &index) const +{ + if (!index.isValid()) + return Qt::ItemIsEnabled; + + return Qt::ItemIsEnabled | Qt::ItemIsSelectable; +} + +/*! + Changes an item in the model, but only if the following conditions + are met: + + * The index supplied is valid. + * The role associated with editing text is specified. + + The dataChanged() signal is emitted if the item is changed. +*/ + +bool TableModel::setData(const QModelIndex &index, + const QVariant &value, int role) +{ + if (!index.isValid() || role != Qt::EditRole) + return false; + + rowList[index.row()][index.column()] = value.toString(); + emit dataChanged(index, index); + return true; +} + +/*! + Inserts a number of rows into the model at the specified position. +*/ + +bool TableModel::insertRows(int position, int rows, const QModelIndex &parent) +{ + int columns = columnCount(); + beginInsertRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + QStringList items; + for (int column = 0; column < columns; ++column) + items.append(""); + rowList.insert(position, items); + } + + endInsertRows(); + return true; +} + +/*! + Inserts a number of columns into the model at the specified position. + Each entry in the list is extended in turn with the required number of + empty strings. +*/ + +bool TableModel::insertColumns(int position, int columns, + const QModelIndex &parent) +{ + int rows = rowCount(); + beginInsertColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = position; column < columns; ++column) { + rowList[row].insert(position, ""); + } + } + + endInsertColumns(); + return true; +} + +/*! + Removes a number of rows from the model at the specified position. +*/ + +bool TableModel::removeRows(int position, int rows, const QModelIndex &parent) +{ + beginRemoveRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + rowList.removeAt(position); + } + + endRemoveRows(); + return true; +} + +/*! + Removes a number of columns from the model at the specified position. + Each row is shortened by the number of columns specified. +*/ + +bool TableModel::removeColumns(int position, int columns, + const QModelIndex &parent) +{ + int rows = rowCount(); + beginRemoveColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = 0; column < columns; ++column) { + rowList[row].removeAt(position); + } + } + + endRemoveColumns(); + return true; +} diff --git a/src/widgets/doc/snippets/reading-selections/model.h b/src/widgets/doc/snippets/reading-selections/model.h new file mode 100644 index 0000000000..ef63e45ce0 --- /dev/null +++ b/src/widgets/doc/snippets/reading-selections/model.h @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 MODEL_H +#define MODEL_H + +#include <QAbstractTableModel> +#include <QStringList> +#include <QVariant> + +class TableModel : public QAbstractTableModel +{ + Q_OBJECT + +public: + TableModel(int rows = 1, int columns = 1, QObject *parent = 0); + + int rowCount(const QModelIndex &parent = QModelIndex()) const; + int columnCount(const QModelIndex &parent = QModelIndex()) const; + QVariant data(const QModelIndex &index, int role) const; + QVariant headerData(int section, Qt::Orientation orientation, + int role = Qt::DisplayRole) const; + + Qt::ItemFlags flags(const QModelIndex &index) const; + bool setData(const QModelIndex &index, const QVariant &value, + int role = Qt::EditRole); + + bool insertRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool insertColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + bool removeRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool removeColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + +private: + QList<QStringList> rowList; +}; + +#endif diff --git a/src/widgets/doc/snippets/reading-selections/reading-selections.pro b/src/widgets/doc/snippets/reading-selections/reading-selections.pro new file mode 100644 index 0000000000..91ebd3e84f --- /dev/null +++ b/src/widgets/doc/snippets/reading-selections/reading-selections.pro @@ -0,0 +1,2 @@ +HEADERS += model.h window.h +SOURCES += main.cpp model.cpp window.cpp diff --git a/src/widgets/doc/snippets/reading-selections/window.cpp b/src/widgets/doc/snippets/reading-selections/window.cpp new file mode 100644 index 0000000000..dd9970374f --- /dev/null +++ b/src/widgets/doc/snippets/reading-selections/window.cpp @@ -0,0 +1,120 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + window.cpp + + A minimal subclass of QTableView with slots to allow the selection model + to be monitored. +*/ + +#include <QAbstractItemModel> +#include <QItemSelection> +#include <QItemSelectionModel> +#include <QMenu> +#include <QMenuBar> +#include <QStatusBar> + +#include "model.h" +#include "window.h" + +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ + setWindowTitle("Selected Items in a Table Model"); + + model = new TableModel(8, 4, this); + + table = new QTableView(this); + table->setModel(model); + + QMenu *actionMenu = new QMenu(tr("&Actions"), this); + QAction *fillAction = actionMenu->addAction(tr("&Fill Selection")); + QAction *clearAction = actionMenu->addAction(tr("&Clear Selection")); + QAction *selectAllAction = actionMenu->addAction(tr("&Select All")); + menuBar()->addMenu(actionMenu); + + connect(fillAction, SIGNAL(triggered()), this, SLOT(fillSelection())); + connect(clearAction, SIGNAL(triggered()), this, SLOT(clearSelection())); + connect(selectAllAction, SIGNAL(triggered()), this, SLOT(selectAll())); + + selectionModel = table->selectionModel(); + + statusBar(); + setCentralWidget(table); +} + +void MainWindow::fillSelection() +{ +//! [0] + QModelIndexList indexes = selectionModel->selectedIndexes(); + QModelIndex index; + + foreach(index, indexes) { + QString text = QString("(%1,%2)").arg(index.row()).arg(index.column()); + model->setData(index, text); + } +//! [0] +} + +void MainWindow::clearSelection() +{ + QModelIndexList indexes = selectionModel->selectedIndexes(); + QModelIndex index; + + foreach(index, indexes) + model->setData(index, ""); +} + +void MainWindow::selectAll() +{ +//! [1] + QModelIndex parent = QModelIndex(); +//! [1] //! [2] + QModelIndex topLeft = model->index(0, 0, parent); + QModelIndex bottomRight = model->index(model->rowCount(parent)-1, + model->columnCount(parent)-1, parent); +//! [2] + +//! [3] + QItemSelection selection(topLeft, bottomRight); + selectionModel->select(selection, QItemSelectionModel::Select); +//! [3] +} diff --git a/src/widgets/doc/snippets/reading-selections/window.h b/src/widgets/doc/snippets/reading-selections/window.h new file mode 100644 index 0000000000..6d2537c22d --- /dev/null +++ b/src/widgets/doc/snippets/reading-selections/window.h @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 WINDOW_H +#define WINDOW_H + +#include <QItemSelection> +#include <QMainWindow> +#include <QAbstractItemModel> +#include <QWidget> +#include <QTableView> + +class MainWindow : public QMainWindow +{ + Q_OBJECT +public: + MainWindow(QWidget *parent = 0); + +private slots: + void fillSelection(); + void clearSelection(); + void selectAll(); + +private: + QAbstractItemModel *model; + QItemSelectionModel *selectionModel; + QTableView *table; +}; + +#endif diff --git a/src/widgets/doc/snippets/sharedtablemodel/main.cpp b/src/widgets/doc/snippets/sharedtablemodel/main.cpp new file mode 100644 index 0000000000..f031a02aca --- /dev/null +++ b/src/widgets/doc/snippets/sharedtablemodel/main.cpp @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + main.cpp + + A simple example that shows how a single model can be shared between + multiple views. +*/ + +#include <QApplication> +#include <QHeaderView> +#include <QItemSelectionModel> +#include <QTableView> + +#include "model.h" + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + TableModel *model = new TableModel(4, 2, &app); + +//! [0] + QTableView *firstTableView = new QTableView; + QTableView *secondTableView = new QTableView; +//! [0] + +//! [1] + firstTableView->setModel(model); + secondTableView->setModel(model); +//! [1] + + firstTableView->horizontalHeader()->setModel(model); + + for (int row = 0; row < 4; ++row) { + for (int column = 0; column < 2; ++column) { + QModelIndex index = model->index(row, column, QModelIndex()); + model->setData(index, QVariant(QString("(%1, %2)").arg(row).arg(column))); + } + } + +//! [2] + secondTableView->setSelectionModel(firstTableView->selectionModel()); +//! [2] + + firstTableView->setWindowTitle("First table view"); + secondTableView->setWindowTitle("Second table view"); + firstTableView->show(); + secondTableView->show(); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/sharedtablemodel/model.cpp b/src/widgets/doc/snippets/sharedtablemodel/model.cpp new file mode 100644 index 0000000000..ec56f84adb --- /dev/null +++ b/src/widgets/doc/snippets/sharedtablemodel/model.cpp @@ -0,0 +1,236 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + model.cpp + + Provides a table model for use in various examples. +*/ + +#include <QtGui> + +#include "model.h" + +/*! + Constructs a table model with at least one row and one column. +*/ + +TableModel::TableModel(int rows, int columns, QObject *parent) + : QAbstractTableModel(parent) +{ + QStringList newList; + + for (int column = 0; column < qMax(1, columns); ++column) { + newList.append(""); + } + + for (int row = 0; row < qMax(1, rows); ++row) { + rowList.append(newList); + } +} + + +/*! + Returns the number of items in the row list as the number of rows + in the model. +*/ + +int TableModel::rowCount(const QModelIndex &/*parent*/) const +{ + return rowList.size(); +} + +/*! + Returns the number of items in the first list item as the number of + columns in the model. All rows should have the same number of columns. +*/ + +int TableModel::columnCount(const QModelIndex &/*parent*/) const +{ + return rowList[0].size(); +} + +/*! + Returns an appropriate value for the requested data. + If the view requests an invalid index, an invalid variant is returned. + Any valid index that corresponds to a string in the list causes that + string to be returned for the display role; otherwise an invalid variant + is returned. +*/ + +QVariant TableModel::data(const QModelIndex &index, int role) const +{ + if (!index.isValid()) + return QVariant(); + + if (role == Qt::DisplayRole) + return rowList[index.row()][index.column()]; + else + return QVariant(); +} + +/*! + Returns the appropriate header string depending on the orientation of + the header and the section. If anything other than the display role is + requested, we return an invalid variant. +*/ + +QVariant TableModel::headerData(int section, Qt::Orientation orientation, + int role) const +{ + if (role != Qt::DisplayRole) + return QVariant(); + + if (orientation == Qt::Horizontal) + return QString("Column %1").arg(section); + else + return QString("Row %1").arg(section); +} + +/*! + Returns an appropriate value for the item's flags. Valid items are + enabled, selectable, and editable. +*/ + +Qt::ItemFlags TableModel::flags(const QModelIndex &index) const +{ + if (!index.isValid()) + return Qt::ItemIsEnabled; + + return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable; +} + +/*! + Changes an item in the model, but only if the following conditions + are met: + + * The index supplied is valid. + * The role associated with editing text is specified. + + The dataChanged() signal is emitted if the item is changed. +*/ + +bool TableModel::setData(const QModelIndex &index, + const QVariant &value, int role) +{ + if (!index.isValid() || role != Qt::EditRole) + return false; + + rowList[index.row()][index.column()] = value.toString(); + emit dataChanged(index, index); + return true; +} + +/*! + Inserts a number of rows into the model at the specified position. +*/ + +bool TableModel::insertRows(int position, int rows, const QModelIndex &parent) +{ + int columns = columnCount(); + beginInsertRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + QStringList items; + for (int column = 0; column < columns; ++column) + items.append(""); + rowList.insert(position, items); + } + + endInsertRows(); + return true; +} + +/*! + Inserts a number of columns into the model at the specified position. + Each entry in the list is extended in turn with the required number of + empty strings. +*/ + +bool TableModel::insertColumns(int position, int columns, const QModelIndex &parent) +{ + int rows = rowCount(); + beginInsertColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = position; column < columns; ++column) { + rowList[row].insert(position, ""); + } + } + + endInsertColumns(); + return true; +} + +/*! + Removes a number of rows from the model at the specified position. +*/ + +bool TableModel::removeRows(int position, int rows, const QModelIndex &parent) +{ + beginRemoveRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + rowList.removeAt(position); + } + + endRemoveRows(); + return true; +} + +/*! + Removes a number of columns from the model at the specified position. + Each row is shortened by the number of columns specified. +*/ + +bool TableModel::removeColumns(int position, int columns, const QModelIndex &parent) +{ + int rows = rowCount(); + beginRemoveColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = 0; column < columns; ++column) { + rowList[row].removeAt(position); + } + } + + endRemoveColumns(); + return true; +} diff --git a/src/widgets/doc/snippets/sharedtablemodel/model.h b/src/widgets/doc/snippets/sharedtablemodel/model.h new file mode 100644 index 0000000000..ef63e45ce0 --- /dev/null +++ b/src/widgets/doc/snippets/sharedtablemodel/model.h @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 MODEL_H +#define MODEL_H + +#include <QAbstractTableModel> +#include <QStringList> +#include <QVariant> + +class TableModel : public QAbstractTableModel +{ + Q_OBJECT + +public: + TableModel(int rows = 1, int columns = 1, QObject *parent = 0); + + int rowCount(const QModelIndex &parent = QModelIndex()) const; + int columnCount(const QModelIndex &parent = QModelIndex()) const; + QVariant data(const QModelIndex &index, int role) const; + QVariant headerData(int section, Qt::Orientation orientation, + int role = Qt::DisplayRole) const; + + Qt::ItemFlags flags(const QModelIndex &index) const; + bool setData(const QModelIndex &index, const QVariant &value, + int role = Qt::EditRole); + + bool insertRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool insertColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + bool removeRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool removeColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + +private: + QList<QStringList> rowList; +}; + +#endif diff --git a/src/widgets/doc/snippets/sharedtablemodel/sharedtablemodel.pro b/src/widgets/doc/snippets/sharedtablemodel/sharedtablemodel.pro new file mode 100644 index 0000000000..10671e6e25 --- /dev/null +++ b/src/widgets/doc/snippets/sharedtablemodel/sharedtablemodel.pro @@ -0,0 +1,2 @@ +HEADERS += model.h +SOURCES += main.cpp model.cpp diff --git a/src/widgets/doc/snippets/simplemodel-use/main.cpp b/src/widgets/doc/snippets/simplemodel-use/main.cpp new file mode 100644 index 0000000000..d8188b14e6 --- /dev/null +++ b/src/widgets/doc/snippets/simplemodel-use/main.cpp @@ -0,0 +1,95 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + main.cpp + + A simple example of how to access items from an existing model. +*/ + +#include <QtGui> + +/*! + Create a default directory model and, using the index-based interface to + the model and some QLabel widgets, populate the window's layout with the + names of objects in the directory. + + Note that we only want to read the filenames in the highest level of the + directory, so we supply a default (invalid) QModelIndex to the model in + order to indicate that we want top-level items. +*/ + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QWidget *window = new QWidget; + QVBoxLayout *layout = new QVBoxLayout(window); + QLabel *title = new QLabel("Some items from the directory model", window); + title->setBackgroundRole(QPalette::Base); + title->setMargin(8); + layout->addWidget(title); + +//! [0] + QFileSystemModel *model = new QFileSystemModel; + QModelIndex parentIndex = model->index(QDir::currentPath()); + int numRows = model->rowCount(parentIndex); +//! [0] + +//! [1] + for (int row = 0; row < numRows; ++row) { + QModelIndex index = model->index(row, 0, parentIndex); +//! [1] + +//! [2] + QString text = model->data(index, Qt::DisplayRole).toString(); + // Display the text in a widget. +//! [2] + + QLabel *label = new QLabel(text, window); + layout->addWidget(label); +//! [3] + } +//! [3] + + window->setWindowTitle("A simple model example"); + window->show(); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/simplemodel-use/simplemodel-use.pro b/src/widgets/doc/snippets/simplemodel-use/simplemodel-use.pro new file mode 100644 index 0000000000..28dcadcbfa --- /dev/null +++ b/src/widgets/doc/snippets/simplemodel-use/simplemodel-use.pro @@ -0,0 +1 @@ +SOURCES += main.cpp diff --git a/src/widgets/doc/snippets/stringlistmodel/main.cpp b/src/widgets/doc/snippets/stringlistmodel/main.cpp new file mode 100644 index 0000000000..d4f0efdc22 --- /dev/null +++ b/src/widgets/doc/snippets/stringlistmodel/main.cpp @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/*! + The main function for the string list model example. This creates and + populates a model with values from a string list then displays the + contents of the model using a QListView widget. +*/ + +#include <QAbstractItemModel> +#include <QApplication> +#include <QListView> + +#include "model.h" + +//! [0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + +// Unindented for quoting purposes: +//! [1] +QStringList numbers; +numbers << "One" << "Two" << "Three" << "Four" << "Five"; + +QAbstractItemModel *model = new StringListModel(numbers); +//! [0] //! [1] //! [2] //! [3] +QListView *view = new QListView; +//! [2] +view->setWindowTitle("View onto a string list model"); +//! [4] +view->setModel(model); +//! [3] //! [4] + + model->insertRows(5, 7, QModelIndex()); + + for (int row = 5; row < 12; ++row) { + QModelIndex index = model->index(row, 0, QModelIndex()); + model->setData(index, QString::number(row+1)); + } + +//! [5] + view->show(); + return app.exec(); +} +//! [5] diff --git a/src/widgets/doc/snippets/stringlistmodel/model.cpp b/src/widgets/doc/snippets/stringlistmodel/model.cpp new file mode 100644 index 0000000000..6795345d36 --- /dev/null +++ b/src/widgets/doc/snippets/stringlistmodel/model.cpp @@ -0,0 +1,211 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + model.cpp + + A simple model that uses a QStringList as its data source. +*/ + +#include "model.h" + +/*! + Returns the number of items in the string list as the number of rows + in the model. +*/ + +//! [0] +int StringListModel::rowCount(const QModelIndex &parent) const +{ + return stringList.count(); +} +//! [0] + + +#ifdef 0 +// This represents a read-only version of data(), an early stage in the +// development of the example leading to an editable StringListModel. + +/*! + Returns an appropriate value for the requested data. + If the view requests an invalid index, an invalid variant is returned. + Any valid index that corresponds to a string in the list causes that + string to be returned. +*/ + +//! [1-data-read-only] +QVariant StringListModel::data(const QModelIndex &index, int role) const +{ + if (!index.isValid()) + return QVariant(); + + if (index.row() >= stringList.size()) + return QVariant(); + + if (role == Qt::DisplayRole) + return stringList.at(index.row()); + else + return QVariant(); +} +//! [1-data-read-only] +#endif + + +/*! + Returns an appropriate value for the requested data. + If the view requests an invalid index, an invalid variant is returned. + Any valid index that corresponds to a string in the list causes that + string to be returned. +*/ + +//! [1] +QVariant StringListModel::data(const QModelIndex &index, int role) const +{ + if (!index.isValid()) + return QVariant(); + + if (index.row() >= stringList.size()) + return QVariant(); + + if (role == Qt::DisplayRole || role == Qt::EditRole) + return stringList.at(index.row()); + else + return QVariant(); +} +//! [1] + +/*! + Returns the appropriate header string depending on the orientation of + the header and the section. If anything other than the display role is + requested, we return an invalid variant. +*/ + +//! [2] +QVariant StringListModel::headerData(int section, Qt::Orientation orientation, + int role) const +{ + if (role != Qt::DisplayRole) + return QVariant(); + + if (orientation == Qt::Horizontal) + return QString("Column %1").arg(section); + else + return QString("Row %1").arg(section); +} +//! [2] + +/*! + Returns an appropriate value for the item's flags. Valid items are + enabled, selectable, and editable. +*/ + +//! [3] +Qt::ItemFlags StringListModel::flags(const QModelIndex &index) const +{ + if (!index.isValid()) + return Qt::ItemIsEnabled; + + return QAbstractItemModel::flags(index) | Qt::ItemIsEditable; +} +//! [3] + +/*! + Changes an item in the string list, but only if the following conditions + are met: + + * The index supplied is valid. + * The index corresponds to an item to be shown in a view. + * The role associated with editing text is specified. + + The dataChanged() signal is emitted if the item is changed. +*/ + +//! [4] +bool StringListModel::setData(const QModelIndex &index, + const QVariant &value, int role) +{ + if (index.isValid() && role == Qt::EditRole) { + + stringList.replace(index.row(), value.toString()); + emit dataChanged(index, index); + return true; + } +//! [4] //! [5] + return false; +} +//! [5] + +/*! + Inserts a number of rows into the model at the specified position. +*/ + +//! [6] +bool StringListModel::insertRows(int position, int rows, const QModelIndex &parent) +{ + beginInsertRows(QModelIndex(), position, position+rows-1); + + for (int row = 0; row < rows; ++row) { + stringList.insert(position, ""); + } + + endInsertRows(); + return true; +//! [6] //! [7] +} +//! [7] + +/*! + Removes a number of rows from the model at the specified position. +*/ + +//! [8] +bool StringListModel::removeRows(int position, int rows, const QModelIndex &parent) +{ + beginRemoveRows(QModelIndex(), position, position+rows-1); + + for (int row = 0; row < rows; ++row) { + stringList.removeAt(position); + } + + endRemoveRows(); + return true; +//! [8] //! [9] +} +//! [9] diff --git a/src/widgets/doc/snippets/stringlistmodel/model.h b/src/widgets/doc/snippets/stringlistmodel/model.h new file mode 100644 index 0000000000..1dceccb8a8 --- /dev/null +++ b/src/widgets/doc/snippets/stringlistmodel/model.h @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 MODEL_H +#define MODEL_H + +#include <QAbstractListModel> +#include <QObject> +#include <QStringList> + +//! [0] +class StringListModel : public QAbstractListModel +{ + Q_OBJECT + +public: + StringListModel(const QStringList &strings, QObject *parent = 0) + : QAbstractListModel(parent), stringList(strings) {} + + int rowCount(const QModelIndex &parent = QModelIndex()) const; + QVariant data(const QModelIndex &index, int role) const; + QVariant headerData(int section, Qt::Orientation orientation, +//! [0] //! [1] + int role = Qt::DisplayRole) const; +//! [1] + +//! [2] + Qt::ItemFlags flags(const QModelIndex &index) const; + bool setData(const QModelIndex &index, const QVariant &value, +//! [2] //! [3] + int role = Qt::EditRole); +//! [3] + +//! [4] + bool insertRows(int position, int rows, const QModelIndex &index = QModelIndex()); + bool removeRows(int position, int rows, const QModelIndex &index = QModelIndex()); +//! [4] + +//! [5] +private: + QStringList stringList; +}; +//! [5] + +#endif diff --git a/src/widgets/doc/snippets/stringlistmodel/stringlistmodel.pro b/src/widgets/doc/snippets/stringlistmodel/stringlistmodel.pro new file mode 100644 index 0000000000..b1126bfe73 --- /dev/null +++ b/src/widgets/doc/snippets/stringlistmodel/stringlistmodel.pro @@ -0,0 +1,3 @@ +HEADERS = model.h +SOURCES = main.cpp \ + model.cpp diff --git a/src/widgets/doc/snippets/updating-selections/main.cpp b/src/widgets/doc/snippets/updating-selections/main.cpp new file mode 100644 index 0000000000..3356ffc8ab --- /dev/null +++ b/src/widgets/doc/snippets/updating-selections/main.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + main.cpp + + A simple example that shows how selections can be used directly on a model. + It shows the result of some selections made using a table view. +*/ + +#include <QApplication> + +#include "window.h" + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QMainWindow *window = new MainWindow; + window->show(); + window->resize(640, 480); + return app.exec(); +} diff --git a/src/widgets/doc/snippets/updating-selections/model.cpp b/src/widgets/doc/snippets/updating-selections/model.cpp new file mode 100644 index 0000000000..ec56f84adb --- /dev/null +++ b/src/widgets/doc/snippets/updating-selections/model.cpp @@ -0,0 +1,236 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + model.cpp + + Provides a table model for use in various examples. +*/ + +#include <QtGui> + +#include "model.h" + +/*! + Constructs a table model with at least one row and one column. +*/ + +TableModel::TableModel(int rows, int columns, QObject *parent) + : QAbstractTableModel(parent) +{ + QStringList newList; + + for (int column = 0; column < qMax(1, columns); ++column) { + newList.append(""); + } + + for (int row = 0; row < qMax(1, rows); ++row) { + rowList.append(newList); + } +} + + +/*! + Returns the number of items in the row list as the number of rows + in the model. +*/ + +int TableModel::rowCount(const QModelIndex &/*parent*/) const +{ + return rowList.size(); +} + +/*! + Returns the number of items in the first list item as the number of + columns in the model. All rows should have the same number of columns. +*/ + +int TableModel::columnCount(const QModelIndex &/*parent*/) const +{ + return rowList[0].size(); +} + +/*! + Returns an appropriate value for the requested data. + If the view requests an invalid index, an invalid variant is returned. + Any valid index that corresponds to a string in the list causes that + string to be returned for the display role; otherwise an invalid variant + is returned. +*/ + +QVariant TableModel::data(const QModelIndex &index, int role) const +{ + if (!index.isValid()) + return QVariant(); + + if (role == Qt::DisplayRole) + return rowList[index.row()][index.column()]; + else + return QVariant(); +} + +/*! + Returns the appropriate header string depending on the orientation of + the header and the section. If anything other than the display role is + requested, we return an invalid variant. +*/ + +QVariant TableModel::headerData(int section, Qt::Orientation orientation, + int role) const +{ + if (role != Qt::DisplayRole) + return QVariant(); + + if (orientation == Qt::Horizontal) + return QString("Column %1").arg(section); + else + return QString("Row %1").arg(section); +} + +/*! + Returns an appropriate value for the item's flags. Valid items are + enabled, selectable, and editable. +*/ + +Qt::ItemFlags TableModel::flags(const QModelIndex &index) const +{ + if (!index.isValid()) + return Qt::ItemIsEnabled; + + return Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable; +} + +/*! + Changes an item in the model, but only if the following conditions + are met: + + * The index supplied is valid. + * The role associated with editing text is specified. + + The dataChanged() signal is emitted if the item is changed. +*/ + +bool TableModel::setData(const QModelIndex &index, + const QVariant &value, int role) +{ + if (!index.isValid() || role != Qt::EditRole) + return false; + + rowList[index.row()][index.column()] = value.toString(); + emit dataChanged(index, index); + return true; +} + +/*! + Inserts a number of rows into the model at the specified position. +*/ + +bool TableModel::insertRows(int position, int rows, const QModelIndex &parent) +{ + int columns = columnCount(); + beginInsertRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + QStringList items; + for (int column = 0; column < columns; ++column) + items.append(""); + rowList.insert(position, items); + } + + endInsertRows(); + return true; +} + +/*! + Inserts a number of columns into the model at the specified position. + Each entry in the list is extended in turn with the required number of + empty strings. +*/ + +bool TableModel::insertColumns(int position, int columns, const QModelIndex &parent) +{ + int rows = rowCount(); + beginInsertColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = position; column < columns; ++column) { + rowList[row].insert(position, ""); + } + } + + endInsertColumns(); + return true; +} + +/*! + Removes a number of rows from the model at the specified position. +*/ + +bool TableModel::removeRows(int position, int rows, const QModelIndex &parent) +{ + beginRemoveRows(parent, position, position + rows - 1); + + for (int row = 0; row < rows; ++row) { + rowList.removeAt(position); + } + + endRemoveRows(); + return true; +} + +/*! + Removes a number of columns from the model at the specified position. + Each row is shortened by the number of columns specified. +*/ + +bool TableModel::removeColumns(int position, int columns, const QModelIndex &parent) +{ + int rows = rowCount(); + beginRemoveColumns(parent, position, position + columns - 1); + + for (int row = 0; row < rows; ++row) { + for (int column = 0; column < columns; ++column) { + rowList[row].removeAt(position); + } + } + + endRemoveColumns(); + return true; +} diff --git a/src/widgets/doc/snippets/updating-selections/model.h b/src/widgets/doc/snippets/updating-selections/model.h new file mode 100644 index 0000000000..ef63e45ce0 --- /dev/null +++ b/src/widgets/doc/snippets/updating-selections/model.h @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 MODEL_H +#define MODEL_H + +#include <QAbstractTableModel> +#include <QStringList> +#include <QVariant> + +class TableModel : public QAbstractTableModel +{ + Q_OBJECT + +public: + TableModel(int rows = 1, int columns = 1, QObject *parent = 0); + + int rowCount(const QModelIndex &parent = QModelIndex()) const; + int columnCount(const QModelIndex &parent = QModelIndex()) const; + QVariant data(const QModelIndex &index, int role) const; + QVariant headerData(int section, Qt::Orientation orientation, + int role = Qt::DisplayRole) const; + + Qt::ItemFlags flags(const QModelIndex &index) const; + bool setData(const QModelIndex &index, const QVariant &value, + int role = Qt::EditRole); + + bool insertRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool insertColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + bool removeRows(int position, int rows, const QModelIndex &parent = QModelIndex()); + bool removeColumns(int position, int columns, const QModelIndex &parent = QModelIndex()); + +private: + QList<QStringList> rowList; +}; + +#endif diff --git a/src/widgets/doc/snippets/updating-selections/updating-selections.pro b/src/widgets/doc/snippets/updating-selections/updating-selections.pro new file mode 100644 index 0000000000..91ebd3e84f --- /dev/null +++ b/src/widgets/doc/snippets/updating-selections/updating-selections.pro @@ -0,0 +1,2 @@ +HEADERS += model.h window.h +SOURCES += main.cpp model.cpp window.cpp diff --git a/src/widgets/doc/snippets/updating-selections/window.cpp b/src/widgets/doc/snippets/updating-selections/window.cpp new file mode 100644 index 0000000000..eaa37b8c87 --- /dev/null +++ b/src/widgets/doc/snippets/updating-selections/window.cpp @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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$ +** +****************************************************************************/ + +/* + window.cpp + + A minimal subclass of QTableView with slots to allow the selection model + to be monitored. +*/ + +#include <QAbstractItemModel> +#include <QItemSelection> +#include <QItemSelectionModel> +#include <QStatusBar> + +#include "model.h" +#include "window.h" + +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ + setWindowTitle("Selected items in a table model"); + + model = new TableModel(8, 4, this); + + table = new QTableView(this); + table->setModel(model); + + selectionModel = table->selectionModel(); + connect(selectionModel, + SIGNAL(selectionChanged(const QItemSelection &, const QItemSelection &)), + this, SLOT(updateSelection(const QItemSelection &, const QItemSelection &))); + connect(selectionModel, + SIGNAL(currentChanged(const QModelIndex &, const QModelIndex &)), + this, SLOT(changeCurrent(const QModelIndex &, const QModelIndex &))); + + statusBar(); + setCentralWidget(table); +} + +//! [0] +void MainWindow::updateSelection(const QItemSelection &selected, + const QItemSelection &deselected) +{ + QModelIndex index; + QModelIndexList items = selected.indexes(); + + foreach (index, items) { + QString text = QString("(%1,%2)").arg(index.row()).arg(index.column()); + model->setData(index, text); +//! [0] //! [1] + } +//! [1] + +//! [2] + items = deselected.indexes(); + + foreach (index, items) + model->setData(index, ""); +} +//! [2] + +//! [3] +void MainWindow::changeCurrent(const QModelIndex ¤t, + const QModelIndex &previous) +{ + statusBar()->showMessage( + tr("Moved from (%1,%2) to (%3,%4)") + .arg(previous.row()).arg(previous.column()) + .arg(current.row()).arg(current.column())); +} +//! [3] diff --git a/src/widgets/doc/snippets/updating-selections/window.h b/src/widgets/doc/snippets/updating-selections/window.h new file mode 100644 index 0000000000..0d87ced010 --- /dev/null +++ b/src/widgets/doc/snippets/updating-selections/window.h @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** 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 Nokia Corporation 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 WINDOW_H +#define WINDOW_H + +#include <QItemSelection> +#include <QMainWindow> +#include <QModelIndex> +#include <QWidget> +#include <QTableView> + +class MainWindow : public QMainWindow +{ + Q_OBJECT +public: + MainWindow(QWidget *parent = 0); + +public slots: + void updateSelection(const QItemSelection &selected, + const QItemSelection &deselected); + void changeCurrent(const QModelIndex ¤t, const QModelIndex &previous); + +private: + QAbstractItemModel *model; + QItemSelectionModel *selectionModel; + QTableView *table; +}; + +#endif diff --git a/doc/src/snippets/widgets-tutorial/template.cpp b/src/widgets/doc/snippets/widgets-tutorial/template.cpp index 187952d44d..187952d44d 100644 --- a/doc/src/snippets/widgets-tutorial/template.cpp +++ b/src/widgets/doc/snippets/widgets-tutorial/template.cpp diff --git a/doc/src/widgets/addressbook-fr.qdoc b/src/widgets/doc/src/addressbook-fr.qdoc index edd53239d0..edd53239d0 100644 --- a/doc/src/widgets/addressbook-fr.qdoc +++ b/src/widgets/doc/src/addressbook-fr.qdoc diff --git a/doc/src/widgets/addressbook.qdoc b/src/widgets/doc/src/addressbook.qdoc index 27bdb0fac4..27bdb0fac4 100644 --- a/doc/src/widgets/addressbook.qdoc +++ b/src/widgets/doc/src/addressbook.qdoc diff --git a/src/widgets/doc/src/model-view-programming.qdoc b/src/widgets/doc/src/model-view-programming.qdoc new file mode 100644 index 0000000000..0e48efbff8 --- /dev/null +++ b/src/widgets/doc/src/model-view-programming.qdoc @@ -0,0 +1,2339 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group model-view + \title Model/View Classes +*/ + +/*! + \page model-view-programming.html + \ingroup qt-basic-concepts + + \title Model/View Programming + \brief A guide to Qt's extensible model/view architecture. + + \section1 Introduction to Model/View Programming + + Qt 4 introduced a new set of item view classes that use a model/view + architecture to manage the relationship between data and the way it + is presented to the user. The separation of functionality introduced by + this architecture gives developers greater flexibility to customize the + presentation of items, and provides a standard model interface to allow + a wide range of data sources to be used with existing item views. + In this document, we give a brief introduction to the model/view paradigm, + outline the concepts involved, and describe the architecture of the item + view system. Each of the components in the architecture is explained, + and examples are given that show how to use the classes provided. + + \section2 The model/view architecture + + Model-View-Controller (MVC) is a design pattern originating from + Smalltalk that is often used when building user interfaces. + In \l{Design Patterns}, Gamma et al. write: + + \quotation + MVC consists of three kinds of objects. The Model is the application + object, the View is its screen presentation, and the Controller defines + the way the user interface reacts to user input. Before MVC, user + interface designs tended to lump these objects together. MVC decouples + them to increase flexibility and reuse. + \endquotation + + If the view and the controller objects are combined, the result is + the model/view architecture. This still separates the way that data + is stored from the way that it is presented to the user, but provides + a simpler framework based on the same principles. This separation + makes it possible to display the same data in several different views, + and to implement new types of views, without changing the underlying + data structures. + To allow flexible handling of user input, we introduce the concept of + the \e delegate. The advantage of having a delegate in this framework + is that it allows the way items of data are rendered and edited to be + customized. + + \table + \row \li \inlineimage modelview-overview.png + \li \b{The model/view architecture} + + The model communicates with a source of data, providing an \e interface + for the other components in the architecture. The nature of the + communication depends on the type of data source, and the way the model + is implemented. + + The view obtains \e{model indexes} from the model; these are references + to items of data. By supplying model indexes to the model, the view can + retrieve items of data from the data source. + + In standard views, a \e delegate renders the items of data. When an item + is edited, the delegate communicates with the model directly using + model indexes. + \endtable + + Generally, the model/view classes can be separated into the three groups + described above: models, views, and delegates. Each of these components + is defined by \e abstract classes that provide common interfaces and, + in some cases, default implementations of features. + Abstract classes are meant to be subclassed in order to provide the full + set of functionality expected by other components; this also allows + specialized components to be written. + + Models, views, and delegates communicate with each other using \e{signals + and slots}: + + \list + \li Signals from the model inform the view about changes to the data + held by the data source. + \li Signals from the view provide information about the user's interaction + with the items being displayed. + \li Signals from the delegate are used during editing to tell the + model and view about the state of the editor. + \endlist + + \section3 Models + + All item models are based on the QAbstractItemModel class. This class + defines an interface that is used by views and delegates to access data. + The data itself does not have to be stored in the model; it can be held + in a data structure or repository provided by a separate class, a file, + a database, or some other application component. + + The basic concepts surrounding models are presented in the section + on \l{Model Classes}. + + QAbstractItemModel + provides an interface to data that is flexible enough to handle views + that represent data in the form of tables, lists, and trees. However, + when implementing new models for list and table-like data structures, + the QAbstractListModel and QAbstractTableModel classes are better + starting points because they provide appropriate default implementations + of common functions. Each of these classes can be subclassed to provide + models that support specialized kinds of lists and tables. + + The process of subclassing models is discussed in the section on + \l{Creating New Models}. + + Qt provides some ready-made models that can be used to handle items of + data: + + \list + \li QStringListModel is used to store a simple list of QString items. + \li QStandardItemModel manages more complex tree structures of items, each + of which can contain arbitrary data. + \li QFileSystemModel provides information about files and directories in the + local filing system. + \li QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel are used + to access databases using model/view conventions. + \endlist + + If these standard models do not meet your requirements, you can subclass + QAbstractItemModel, QAbstractListModel, or QAbstractTableModel to create + your own custom models. + + \section3 Views + + Complete implementations are provided for different kinds of + views: QListView displays a list of items, QTableView displays data + from a model in a table, and QTreeView shows model items of data in a + hierarchical list. Each of these classes is based on the + QAbstractItemView abstract base class. Although these classes are + ready-to-use implementations, they can also be subclassed to provide + customized views. + + The available views are examined in the section on \l{View Classes}. + + \section3 Delegates + + QAbstractItemDelegate is the abstract base class for delegates in the + model/view framework. Since Qt 4.4, the default delegate implementation is + provided by QStyledItemDelegate, and this is used as the default delegate + by Qt's standard views. However, QStyledItemDelegate and QItemDelegate are + independent alternatives to painting and providing editors for items in + views. The difference between them is that QStyledItemDelegate uses the + current style to paint its items. We therefore recommend using + QStyledItemDelegate as the base class when implementing custom delegates or + when working with Qt style sheets. + + Delegates are described in the section on \l{Delegate Classes}. + + \section3 Sorting + + There are two ways of approaching sorting in the model/view + architecture; which approach to choose depends on your underlying + model. + + If your model is sortable, i.e, if it reimplements the + QAbstractItemModel::sort() function, both QTableView and QTreeView + provide an API that allows you to sort your model data + programmatically. In addition, you can enable interactive sorting + (i.e. allowing the users to sort the data by clicking the view's + headers), by connecting the QHeaderView::sortIndicatorChanged() signal + to the QTableView::sortByColumn() slot or the + QTreeView::sortByColumn() slot, respectively. + + The alternative approach, if your model do not have the required + interface or if you want to use a list view to present your data, + is to use a proxy model to transform the structure of your model + before presenting the data in the view. This is covered in detail + in the section on \l {Proxy Models}. + + \section3 Convenience classes + + A number of \e convenience classes are derived from the standard view + classes for the benefit of applications that rely on Qt's item-based + item view and table classes. They are not intended to be subclassed, + but simply exist to provide a familiar interface to the equivalent classes + in Qt 3. + Examples of such classes include \l QListWidget, \l QTreeWidget, and + \l QTableWidget; these provide similar behavior to the \c QListBox, + \c QListView, and \c QTable classes in Qt 3. + + These classes are less flexible than the view classes, and cannot be + used with arbitrary models. We recommend that you use a model/view + approach to handling data in item views unless you strongly need an + item-based set of classes. + + If you wish to take advantage of the features provided by the model/view + approach while still using an item-based interface, consider using view + classes, such as QListView, QTableView, and QTreeView with + QStandardItemModel. + + \section1 Using models and views + + The following sections explain how to use the model/view pattern + in Qt. Each section includes an an example and is followed by a + section showing how to create new components. + + \section2 Two models included in Qt + + Two of the standard models provided by Qt are QStandardItemModel and + QFileSystemModel. QStandardItemModel is a multi-purpose model that can be + used to represent various different data structures needed by list, table, + and tree views. This model also holds the items of data. + QFileSystemModel is a model that maintains information about the contents + of a directory. As a result, it does not hold any items of data itself, but + simply represents files and directories on the local filing system. + + QFileSystemModel provides a ready-to-use model to experiment with, and can be + easily configured to use existing data. Using this model, we can show how + to set up a model for use with ready-made views, and explore how to + manipulate data using model indexes. + + \section2 Using views with an existing model + + The QListView and QTreeView classes are the most suitable views + to use with QFileSystemModel. The example presented below displays the + contents of a directory in a tree view next to the same information in + a list view. The views share the user's selection so that the selected + items are highlighted in both views. + + \image shareddirmodel.png + + We set up a QFileSystemModel so that it is ready for use, and create some + views to display the contents of a directory. This shows the simplest + way to use a model. The construction and use of the model is + performed from within a single \c main() function: + + \snippet shareddirmodel/main.cpp 0 + + The model is set up to use data from a certain file system. The call to + \l{QFileSystemModel::}{setRootPath()} tell the model which drive on the + file system to expose to the views. + + We create two views so that we can examine the items held in the model in two + different ways: + + \snippet shareddirmodel/main.cpp 5 + + The views are constructed in the same way as other widgets. Setting up + a view to display the items in the model is simply a matter of calling its + \l{QAbstractItemView::setModel()}{setModel()} function with the directory + model as the argument. We filter the data supplied by the model by calling + the \l{QAbstractItemView::}{setRootIndex()} function on each view, passing + a suitable \e{model index} from the file system model for the current + directory. + + The \c index() function used in this case is unique to QFileSystemModel; we + supply it with a directory and it returns a model index. Model indexes are + discussed in \l{Model Classes}. + + The rest of the function just displays the views within a splitter + widget, and runs the application's event loop: + + \snippet shareddirmodel/main.cpp 8 + + In the above example, we neglected to mention how to handle selections + of items. This subject is covered in more detail in the section about + \l{Handling Selections in Item Views}. + + \section1 Model classes + + Before examining how selections are handled, you may find it + useful to examine the concepts used in the model/view framework. + + \section2 Basic concepts + + In the model/view architecture, the model provides a standard interface + that views and delegates use to access data. In Qt, the standard + interface is defined by the QAbstractItemModel class. No matter how the + items of data are stored in any underlying data structure, all subclasses + of QAbstractItemModel represent the data as a hierarchical structure + containing tables of items. Views use this \e convention to access items + of data in the model, but they are not restricted in the way that they + present this information to the user. + + \image modelview-models.png + + Models also notify any attached views about changes to data through the + signals and slots mechanism. + + This section describes some basic concepts that are central to the way + item of data are accessed by other components via a model class. More + advanced concepts are discussed in later sections. + + \section3 Model indexes + + To ensure that the representation of the data is kept separate from the + way it is accessed, the concept of a \e{model index} is introduced. Each + piece of information that can be obtained via a model is represented by + a model index. Views and delegates use these indexes to request items of + data to display. + + As a result, only the model needs to know how to obtain data, and the type + of data managed by the model can be defined fairly generally. Model indexes + contain a pointer to the model that created them, and this prevents + confusion when working with more than one model. + + \snippet code/doc_src_model-view-programming.cpp 0 + + Model indexes provide \e temporary references to pieces of information, and + can be used to retrieve or modify data via the model. Since models may + reorganize their internal structures from time to time, model indexes may + become invalid, and \e{should not be stored}. If a long-term reference to a + piece of information is required, a \e{persistent model index} must be + created. This provides a reference to the information that the model keeps + up-to-date. Temporary model indexes are provided by the QModelIndex class, + and persistent model indexes are provided by the QPersistentModelIndex + class. + + To obtain a model index that corresponds to an item of data, three + properties must be specified to the model: a row number, a column number, + and the model index of a parent item. The following sections describe + and explain these properties in detail. + + \section3 Rows and columns + + In its most basic form, a model can be accessed as a simple table in which + items are located by their row and column numbers. \e{This does not mean + that the underlying pieces of data are stored in an array structure}; the + use of row and column numbers is only a convention to allow components to + communicate with each other. We can retrieve information about any given + item by specifying its row and column numbers to the model, and we receive + an index that represents the item: + + \snippet code/doc_src_model-view-programming.cpp 1 + + Models that provide interfaces to simple, single level data structures like + lists and tables do not need any other information to be provided but, as + the above code indicates, we need to supply more information when obtaining + a model index. + + \table + \row \li \inlineimage modelview-tablemodel.png + \li \b{Rows and columns} + + The diagram shows a representation of a basic table model in which each + item is located by a pair of row and column numbers. We obtain a model + index that refers to an item of data by passing the relevant row and + column numbers to the model. + + \snippet code/doc_src_model-view-programming.cpp 2 + + Top level items in a model are always referenced by specifying + \c QModelIndex() as their parent item. This is discussed in the next + section. + \endtable + + \section3 Parents of items + + The table-like interface to item data provided by models is ideal when + using data in a table or list view; the row and column number system maps + exactly to the way the views display items. However, structures such as + tree views require the model to expose a more flexible interface to the + items within. As a result, each item can also be the parent of another + table of items, in much the same way that a top-level item in a tree view + can contain another list of items. + + When requesting an index for a model item, we must provide some information + about the item's parent. Outside the model, the only way to refer to an + item is through a model index, so a parent model index must also be given: + + \snippet code/doc_src_model-view-programming.cpp 3 + + \table + \row \li \inlineimage modelview-treemodel.png + \li \b{Parents, rows, and columns} + + The diagram shows a representation of a tree model in which each item is + referred to by a parent, a row number, and a column number. + + Items "A" and "C" are represented as top-level siblings in the model: + + \snippet code/doc_src_model-view-programming.cpp 4 + + Item "A" has a number of children. A model index for item "B" is + obtained with the following code: + + \snippet code/doc_src_model-view-programming.cpp 5 + \endtable + + \section3 Item roles + + Items in a model can perform various \e roles for other components, + allowing different kinds of data to be supplied for different situations. + For example, Qt::DisplayRole is used to access a string that can be + displayed as text in a view. Typically, items contain data for a number of + different roles, and the standard roles are defined by Qt::ItemDataRole. + + We can ask the model for the item's data by passing it the model index + corresponding to the item, and by specifying a role to obtain the type + of data we want: + + \snippet code/doc_src_model-view-programming.cpp 6 + + \table + \row \li \inlineimage modelview-roles.png + \li \b{Item roles} + + The role indicates to the model which type of data is being referred to. + Views can display the roles in different ways, so it is important to + supply appropriate information for each role. + + The \l{Creating New Models} section covers some specific uses of roles in + more detail. + \endtable + + Most common uses for item data are covered by the standard roles defined in + Qt::ItemDataRole. By supplying appropriate item data for each role, models + can provide hints to views and delegates about how items should be + presented to the user. Different kinds of views have the freedom to + interpret or ignore this information as required. It is also possible to + define additional roles for application-specific purposes. + + \section3 Summary + + \list + \li Model indexes give views and delegates information about the location + of items provided by models in a way that is independent of any + underlying data structures. + \li Items are referred to by their row and column numbers, and by the model + index of their parent items. + \li Model indexes are constructed by models at the request of other + components, such as views and delegates. + \li If a valid model index is specified for the parent item when an index is + requested using \l{QAbstractItemModel::index()}{index()}, the index + returned refers to an item beneath that parent item in the model. + The index obtained refers to a child of that item. + \li If an invalid model index is specified for the parent item when an index + is requested using \l{QAbstractItemModel::index()}{index()}, the index + returned refers to a top-level item in the model. + \li The \l{Qt::ItemDataRole}{role} distinguishes between the + different kinds of data associated with an item. + \endlist + + \section2 Using model indexes + + To demonstrate how data can be retrieved from a model, using model + indexes, we set up a QFileSystemModel without a view and display the + names of files and directories in a widget. + Although this does not show a normal way of using a model, it demonstrates + the conventions used by models when dealing with model indexes. + + We construct a file system model in the following way: + + \snippet simplemodel-use/main.cpp 0 + + In this case, we set up a default QFileSystemModel, obtain a parent index + using a specific implementation of \l{QFileSystemModel::}{index()} + provided by that model, and we count the number of rows in the model using + the \l{QFileSystemModel::}{rowCount()} function. + + For simplicity, we are only interested in the items in the first column + of the model. We examine each row in turn, obtaining a model index for + the first item in each row, and read the data stored for that item + in the model. + + \snippet simplemodel-use/main.cpp 1 + + To obtain a model index, we specify the row number, column number (zero + for the first column), and the appropriate model index for the parent + of all the items that we want. + The text stored in each item is retrieved using the model's + \l{QFileSystemModel::}{data()} function. We specify the model index and + the \l{Qt::ItemDataRole}{DisplayRole} to obtain data for the + item in the form of a string. + + \snippet simplemodel-use/main.cpp 2 + \codeline + \snippet simplemodel-use/main.cpp 3 + + The above example demonstrates the basic principles used to retrieve + data from a model: + + \list + \li The dimensions of a model can be found using + \l{QAbstractItemModel::rowCount()}{rowCount()} and + \l{QAbstractItemModel::columnCount()}{columnCount()}. + These functions generally require a parent model index to be + specified. + \li Model indexes are used to access items in the model. The row, column, + and parent model index are needed to specify the item. + \li To access top-level items in a model, specify a null model index + as the parent index with \c QModelIndex(). + \li Items contain data for different roles. To obtain the data for a + particular role, both the model index and the role must be supplied + to the model. + \endlist + + \section2 Further reading + + New models can be created by implementing the standard interface + provided by QAbstractItemModel. In the \l{Creating New Models} + section, we demonstrate this by creating a convenient ready-to-use + model for holding lists of strings. + + \section1 View classes + + \section2 Concepts + + In the model/view architecture, the view obtains items of data from the + model and presents them to the user. The way that the data is + presented need not resemble the representation of the data provided by + the model, and may be \e{completely different} from the underlying data + structure used to store items of data. + + The separation of content and presentation is achieved by the use of a + standard model interface provided by QAbstractItemModel, a standard view + interface provided by QAbstractItemView, and the use of model indexes + that represent items of data in a general way. + Views typically manage the overall layout of the data obtained from + models. They may render individual items of data themselves, or use + \l{Delegate Classes}{delegates} to handle both rendering and editing + features. + + As well as presenting data, views handle navigation between items, + and some aspects of item selection. The views also implement basic + user interface features, such as context menus and drag and drop. + A view can provide default editing facilities for items, or it may + work with a \l{Delegate Classes}{delegate} to provide a custom + editor. + + A view can be constructed without a model, but a model must be + provided before it can display useful information. Views keep track of + the items that the user has selected through the use of + \l{Handling Selections in Item Views}{selections} which can be maintained + separately for each view, or shared between multiple views. + + Some views, such as QTableView and QTreeView, display headers as well + as items. These are also implemented by a view class, QHeaderView. + Headers usually access the same model as the view that contains them. + They retrieve data from the model using the + \l{QAbstractItemModel::headerData()} function, and usually display + header information in the form of a label. New headers can be + subclassed from the QHeaderView class to provide more specialized + labels for views. + + \section2 Using an existing view + + Qt provides three ready-to-use view classes that present data from + models in ways that are familiar to most users. + QListView can display items from a model as a simple list, or in the + form of a classic icon view. QTreeView displays items from a + model as a hierarchy of lists, allowing deeply nested structures to be + represented in a compact way. QTableView presents items from a model + in the form of a table, much like the layout of a spreadsheet + application. + + \image standard-views.png + + The default behavior of the standard views shown above should be + sufficient for most applications. They provide basic editing + facilities, and can be customized to suit the needs of more specialized + user interfaces. + + \section3 Using a model + + We take the string list model that \l{Creating New Models}{we created as + an example model}, set it up with some data, and construct a view to + display the contents of the model. This can all be performed within a + single function: + + \snippet stringlistmodel/main.cpp 0 + + Note that the \c StringListModel is declared as a \l QAbstractItemModel. + This allows us to use the abstract interface to the model, and + ensures that the code still works, even if we replace the string list + model with a different model. + + The list view provided by \l QListView is sufficient for presenting + the items in the string list model. We construct the view, and set up + the model using the following lines of code: + + \snippet stringlistmodel/main.cpp 2 + \snippet stringlistmodel/main.cpp 4 + + The view is shown in the normal way: + + \snippet stringlistmodel/main.cpp 5 + + The view renders the contents of a model, accessing data via the model's + interface. When the user tries to edit an item, the view uses a default + delegate to provide an editor widget. + + \image stringlistmodel.png + + The above image shows how a QListView represents the data in the string + list model. Since the model is editable, the view automatically allows + each item in the list to be edited using the default delegate. + + \section3 Using multiple views of a model + + Providing multiple views onto the same model is simply a matter of + setting the same model for each view. In the following code we create + two table views, each using the same simple table model which we have + created for this example: + + \snippet sharedtablemodel/main.cpp 0 + \codeline + \snippet sharedtablemodel/main.cpp 1 + + The use of signals and slots in the model/view architecture means that + changes to the model can be propagated to all the attached views, + ensuring that we can always access the same data regardless of the + view being used. + + \image sharedmodel-tableviews.png + + The above image shows two different views onto the same model, each + containing a number of selected items. Although the data from the model + is shown consistently across view, each view maintains its own internal + selection model. This can be useful in certain situations but, for + many applications, a shared selection model is desirable. + + \section2 Handling selections of items + + The mechanism for handling selections of items within views is provided + by the \l QItemSelectionModel class. All of the standard views construct + their own selection models by default, and interact with them in the + normal way. The selection model being used by a view can be obtained + through the \l{QAbstractItemView::selectionModel()}{selectionModel()} + function, and a replacement selection model can be specified with + \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}. + The ability to control the selection model used by a view is useful + when we want to provide multiple consistent views onto the same model + data. + + Generally, unless you are subclassing a model or view, you don't + need to manipulate the contents of selections directly. However, + the interface to the selection model can be accessed, if required, + and this is explored in \l{Handling Selections in Item Views}. + + \section3 Sharing selections among views + + Although it is convenient that the view classes provide their own + selection models by default, when we use more than one view onto the + same model it is often desirable that both the model's data and the + user's selection are shown consistently in all views. + Since the view classes allow their internal selection models to be + replaced, we can achieve a unified selection between views with the + following line: + + \snippet sharedtablemodel/main.cpp 2 + + The second view is given the selection model for the first view. + Both views now operate on the same selection model, keeping both + the data and the selected items synchronized. + + \image sharedselection-tableviews.png + + In the example shown above, two views of the same type were used to + display the same model's data. However, if two different types of view + were used, the selected items may be represented very differently in + each view; for example, a contiguous selection in a table view can be + represented as a fragmented set of highlighted items in a tree view. + + \section1 Delegate classes + + \section2 Concepts + + Unlike the Model-View-Controller pattern, the model/view design does not + include a completely separate component for managing interaction with + the user. Generally, the view is responsible for the presentation of + model data to the user, and for processing user input. To allow some + flexibility in the way this input is obtained, the interaction is + performed by delegates. These components provide input capabilities + and are also responsible for rendering individual items in some views. + The standard interface for controlling delegates is defined in the + \l QAbstractItemDelegate class. + + Delegates are expected to be able to render their contents themselves + by implementing the \l{QItemDelegate::paint()}{paint()} + and \l{QItemDelegate::sizeHint()}{sizeHint()} functions. + However, simple widget-based delegates can subclass \l QItemDelegate + instead of \l QAbstractItemDelegate, and take advantage of the default + implementations of these functions. + + Editors for delegates can be implemented either by using widgets to manage + the editing process or by handling events directly. + The first approach is covered later in this section, and it is also + shown in the \l{Spin Box Delegate Example}{Spin Box Delegate} example. + + The \l{Pixelator Example}{Pixelator} example shows how to create a + custom delegate that performs specialized rendering for a table view. + + \section2 Using an existing delegate + + The standard views provided with Qt use instances of \l QItemDelegate + to provide editing facilities. This default implementation of the + delegate interface renders items in the usual style for each of the + standard views: \l QListView, \l QTableView, and \l QTreeView. + + All the standard roles are handled by the default delegate used by + the standard views. The way these are interpreted is described in the + QItemDelegate documentation. + + The delegate used by a view is returned by the + \l{QAbstractItemView::itemDelegate()}{itemDelegate()} function. + The \l{QAbstractItemView::setItemDelegate()}{setItemDelegate()} function + allows you to install a custom delegate for a standard view, and it is + necessary to use this function when setting the delegate for a custom + view. + + \section2 A simple delegate + + The delegate implemented here uses a \l QSpinBox to provide + editing facilities, and is mainly intended for use with models + that display integers. Although we set up a custom integer-based + table model for this purpose, we could easily have used \l + QStandardItemModel instead, since the custom delegate controls + data entry. We construct a table view to display the contents of + the model, and this will use the custom delegate for editing. + + \image spinboxdelegate-example.png + + We subclass the delegate from \l QItemDelegate because we do not want + to write custom display functions. However, we must still provide + functions to manage the editor widget: + + \snippet itemviews/spinboxdelegate/delegate.h 0 + + Note that no editor widgets are set up when the delegate is + constructed. We only construct an editor widget when it is needed. + + \section3 Providing an editor + + In this example, when the table view needs to provide an editor, it + asks the delegate to provide an editor widget that is appropriate + for the item being modified. The + \l{QAbstractItemDelegate::createEditor()}{createEditor()} function is + supplied with everything that the delegate needs to be able to set up + a suitable widget: + + \snippet itemviews/spinboxdelegate/delegate.cpp 1 + + Note that we do not need to keep a pointer to the editor widget because + the view takes responsibility for destroying it when it is no longer + needed. + + We install the delegate's default event filter on the editor to ensure + that it provides the standard editing shortcuts that users expect. + Additional shortcuts can be added to the editor to allow more + sophisticated behavior; these are discussed in the section on + \l{#EditingHints}{Editing Hints}. + + The view ensures that the editor's data and geometry are set + correctly by calling functions that we define later for these purposes. + We can create different editors depending on the model index supplied + by the view. For example, if we have a column of integers and a column + of strings we could return either a \c QSpinBox or a \c QLineEdit, + depending on which column is being edited. + + The delegate must provide a function to copy model data into the + editor. In this example, we read the data stored in the + \l{Qt::ItemDataRole}{display role}, and set the value in the + spin box accordingly. + + \snippet itemviews/spinboxdelegate/delegate.cpp 2 + + In this example, we know that the editor widget is a spin box, but we + could have provided different editors for different types of data in + the model, in which case we would need to cast the widget to the + appropriate type before accessing its member functions. + + \section3 Submitting data to the model + + When the user has finished editing the value in the spin box, the view + asks the delegate to store the edited value in the model by calling the + \l{QAbstractItemDelegate::setModelData()}{setModelData()} function. + + \snippet itemviews/spinboxdelegate/delegate.cpp 3 + + Since the view manages the editor widgets for the delegate, we only + need to update the model with the contents of the editor supplied. + In this case, we ensure that the spin box is up-to-date, and update + the model with the value it contains using the index specified. + + The standard \l QItemDelegate class informs the view when it has + finished editing by emitting the + \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} signal. + The view ensures that the editor widget is closed and destroyed. In + this example, we only provide simple editing facilities, so we need + never emit this signal. + + All the operations on data are performed through the interface + provided by \l QAbstractItemModel. This makes the delegate mostly + independent from the type of data it manipulates, but some + assumptions must be made in order to use certain types of + editor widgets. In this example, we have assumed that the model + always contains integer values, but we can still use this + delegate with different kinds of models because \l{QVariant} + provides sensible default values for unexpected data. + + \section3 Updating the editor's geometry + + It is the responsibility of the delegate to manage the editor's + geometry. The geometry must be set when the editor is created, and + when the item's size or position in the view is changed. Fortunately, + the view provides all the necessary geometry information inside a + \l{QStyleOptionViewItem}{view option} object. + + \snippet itemviews/spinboxdelegate/delegate.cpp 4 + + In this case, we just use the geometry information provided by the + view option in the item rectangle. A delegate that renders items with + several elements would not use the item rectangle directly. It would + position the editor in relation to the other elements in the item. + + \target EditingHints + \section3 Editing hints + + After editing, delegates should provide hints to the other components + about the result of the editing process, and provide hints that will + assist any subsequent editing operations. This is achieved by + emitting the \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} + signal with a suitable hint. This is taken care of by the default + QItemDelegate event filter which we installed on the spin box when + it was constructed. + + The behavior of the spin box could be adjusted to make it more user + friendly. In the default event filter supplied by QItemDelegate, if + the user hits \key Return to confirm their choice in the spin box, + the delegate commits the value to the model and closes the spin box. + We can change this behavior by installing our own event filter on the + spin box, and provide editing hints that suit our needs; for example, + we might emit \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} + with the \l{QAbstractItemDelegate::EndEditHint}{EditNextItem} hint to + automatically start editing the next item in the view. + + Another approach that does not require the use of an event + filter is to provide our own editor widget, perhaps subclassing + QSpinBox for convenience. This alternative approach would give us + more control over how the editor widget behaves at the cost of + writing additional code. It is usually easier to install an event + filter in the delegate if you need to customize the behavior of + a standard Qt editor widget. + + Delegates do not have to emit these hints, but those that do not will + be less integrated into applications, and will be less usable than + those that emit hints to support common editing actions. + + \section1 Handling selections in item views + + \section2 Concepts + + The selection model used in the item view classes offers many improvements + over the selection model used in Qt 3. It provides a more general + description of selections based on the facilities of the model/view + architecture. Although the standard classes for manipulating selections are + sufficient for the item views provided, the selection model allows you to + create specialized selection models to suit the requirements for your own + item models and views. + + Information about the items selected in a view is stored in an instance of + the \l QItemSelectionModel class. This maintains model indexes for items in + a single model, and is independent of any views. Since there can be many + views onto a model, it is possible to share selections between views, + allowing applications to show multiple views in a consistent way. + + Selections are made up of \e{selection ranges}. These efficiently maintain + information about large selections of items by recording only the starting + and ending model indexes for each range of selected items. Non-contiguous + selections of items are constructed by using more than one selection range + to describe the selection. + + Selections are applied to a collection of model indexes held by a selection + model. The most recent selection of items applied is known as the + \e{current selection}. The effects of this selection can be modified even + after its application through the use of certain types of selection + commands. These are discussed later in this section. + + \section3 Current item and selected items + + In a view, there is always a current item and a selected item - two + independent states. An item can be the current item and selected at the + same time. The view is responsible for ensuring that there is always a + current item as keyboard navigation, for example, requires a current item. + + The table below highlights the differences between current item and + selected items. + + \table + \header + \li Current Item + \li Selected Items + + \row + \li There can only be one current item. + \li There can be multiple selected items. + \row + \li The current item will be changed with key navigation or mouse + button clicks. + \li The selected state of items is set or unset, depending on several + pre-defined modes - e.g., single selection, multiple selection, + etc. - when the user interacts with the items. + \row + \li The current item will be edited if the edit key, \uicontrol F2, is + pressed or the item is double-clicked (provided that editing is + enabled). + \li The current item can be used together with an anchor to specify a + range that should be selected or deselected (or a combination of + the two). + \row + \li The current item is indicated by the focus rectangle. + \li The selected items are indicated with the selection rectangle. + \endtable + + When manipulating selections, it is often helpful to think of + \l QItemSelectionModel as a record of the selection state of all the items + in an item model. Once a selection model is set up, collections of items + can be selected, deselected, or their selection states can be toggled + without the need to know which items are already selected. The indexes of + all selected items can be retrieved at any time, and other components can + be informed of changes to the selection model via the signals and slots + mechanism. + + \section2 Using a selection model + + The standard view classes provide default selection models that can + be used in most applications. A selection model belonging to one view + can be obtained using the view's + \l{QAbstractItemView::selectionModel()}{selectionModel()} function, + and shared between many views with + \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}, + so the construction of new selection models is generally not required. + + A selection is created by specifying a model, and a pair of model + indexes to a \l QItemSelection. This uses the indexes to refer to items + in the given model, and interprets them as the top-left and bottom-right + items in a block of selected items. + To apply the selection to items in a model requires the selection to be + submitted to a selection model; this can be achieved in a number of ways, + each having a different effect on the selections already present in the + selection model. + + \section3 Selecting items + + To demonstrate some of the principal features of selections, we construct + an instance of a custom table model with 32 items in total, and open a + table view onto its data: + + \snippet itemselection/main.cpp 0 + + The table view's default selection model is retrieved for later use. + We do not modify any items in the model, but instead select a few + items that the view will display at the top-left of the table. To do + this, we need to retrieve the model indexes corresponding to the + top-left and bottom-right items in the region to be selected: + + \snippet itemselection/main.cpp 1 + + To select these items in the model, and see the corresponding change + in the table view, we need to construct a selection object then apply + it to the selection model: + + \snippet itemselection/main.cpp 2 + + The selection is applied to the selection model using a command + defined by a combination of + \l{QItemSelectionModel::SelectionFlag}{selection flags}. + In this case, the flags used cause the items recorded in the + selection object to be included in the selection model, regardless + of their previous state. The resulting selection is shown by the view. + + \image selected-items1.png + + The selection of items can be modified using various operations that + are defined by the selection flags. The selection that results from + these operations may have a complex structure, but it is represented + efficiently by the selection model. The use of different selection + flags to manipulate the selected items is described when we examine + how to update a selection. + + \section3 Reading the selection state + + The model indexes stored in the selection model can be read using + the \l{QItemSelectionModel::selectedIndexes()}{selectedIndexes()} + function. This returns an unsorted list of model indexes that we can + iterate over as long as we know which model they are for: + + \snippet reading-selections/window.cpp 0 + + The above code uses Qt's convenient \l{Container Classes}{foreach + keyword} to iterate over, and modify, the items corresponding to the + indexes returned by the selection model. + + The selection model emits signals to indicate changes in the + selection. These notify other components about changes to both the + selection as a whole and the currently focused item in the item + model. We can connect the + \l{QItemSelectionModel::selectionChanged()}{selectionChanged()} + signal to a slot, and examine the items in the model that are selected or + deselected when the selection changes. The slot is called with two + \l{QItemSelection} objects: one contains a list of indexes that + correspond to newly selected items; the other contains indexes that + correspond to newly deselected items. + + In the following code, we provide a slot that receives the + \l{QItemSelectionModel::selectionChanged()}{selectionChanged()} + signal, fills in the selected items with + a string, and clears the contents of the deselected items. + + \snippet updating-selections/window.cpp 0 + \snippet updating-selections/window.cpp 1 + \codeline + \snippet updating-selections/window.cpp 2 + + We can keep track of the currently focused item by connecting the + \l{QItemSelectionModel::currentChanged()}{currentChanged()} signal + to a slot that is called with two model indexes. These correspond to + the previously focused item, and the currently focused item. + + In the following code, we provide a slot that receives the + \l{QItemSelectionModel::currentChanged()}{currentChanged()} signal, + and uses the information provided to update the status bar of a + \l QMainWindow: + + \snippet updating-selections/window.cpp 3 + + Monitoring selections made by the user is straightforward with these + signals, but we can also update the selection model directly. + + \section3 Updating a selection + + Selection commands are provided by a combination of selection flags, + defined by \l{QItemSelectionModel::SelectionFlag}. + Each selection flag tells the selection model how to update its + internal record of selected items when either of the + \l{QItemSelection::select()}{select()} functions are called. + The most commonly used flag is the + \l{QItemSelectionModel::SelectionFlag}{Select} flag + which instructs the selection model to record the specified items as + being selected. The + \l{QItemSelectionModel::SelectionFlag}{Toggle} flag causes the + selection model to invert the state of the specified items, + selecting any deselected items given, and deselecting any currently + selected items. The \l{QItemSelectionModel::SelectionFlag}{Deselect} + flag deselects all the specified items. + + Individual items in the selection model are updated by creating a + selection of items, and applying them to the selection model. In the + following code, we apply a second selection of items to the table + model shown above, using the + \l{QItemSelectionModel::SelectionFlag}{Toggle} command to invert the + selection state of the items given. + + \snippet itemselection/main.cpp 3 + + The results of this operation are displayed in the table view, + providing a convenient way of visualizing what we have achieved: + + \image selected-items2.png + + By default, the selection commands only operate on the individual + items specified by the model indexes. However, the flag used to + describe the selection command can be combined with additional flags + to change entire rows and columns. For example if you call + \l{QItemSelectionModel::select()}{select()} with only one index, but + with a command that is a combination of + \l{QItemSelectionModel::SelectionFlag}{Select} and + \l{QItemSelectionModel::SelectionFlag}{Rows}, the + entire row containing the item referred to is selected. + The following code demonstrates the use of the + \l{QItemSelectionModel::SelectionFlag}{Rows} and + \l{QItemSelectionModel::SelectionFlag}{Columns} flags: + + \snippet itemselection/main.cpp 4 + + Although only four indexes are supplied to the selection model, the + use of the + \l{QItemSelectionModel::SelectionFlag}{Columns} and + \l{QItemSelectionModel::SelectionFlag}{Rows} selection flags means + that two columns and two rows are selected. The following image shows + the result of these two selections: + + \image selected-items3.png + + The commands performed on the example model have all involved + accumulating a selection of items in the model. It is also possible + to clear the selection, or to replace the current selection with + a new one. + + To replace the current selection with a new selection, combine + the other selection flags with the + \l{QItemSelectionModel::SelectionFlag}{Current} flag. A command using + this flag instructs the selection model to replace its current collection + of model indexes with those specified in a call to + \l{QItemSelectionModel::select()}{select()}. + To clear all selections before you start adding new ones, + combine the other selection flags with the + \l{QItemSelectionModel::SelectionFlag}{Clear} flag. This + has the effect of resetting the selection model's collection of model + indexes. + + \section3 Selecting all items in a model + + To select all items in a model, it is necessary to create a + selection for each level of the model that covers all items in that + level. We do this by retrieving the indexes corresponding to the + top-left and bottom-right items with a given parent index: + + \snippet reading-selections/window.cpp 2 + + A selection is constructed with these indexes and the model. The + corresponding items are then selected in the selection model: + + \snippet reading-selections/window.cpp 3 + + This needs to be performed for all levels in the model. + For top-level items, we would define the parent index in the usual way: + + \snippet reading-selections/window.cpp 1 + + For hierarchical models, the + \l{QAbstractItemModel::hasChildren()}{hasChildren()} function is used to + determine whether any given item is the parent of another level of + items. + + \section1 Creating new models + + The separation of functionality between the model/view components allows + models to be created that can take advantage of existing views. This + approach lets us present data from a variety of sources using standard + graphical user interface components, such as QListView, QTableView, and + QTreeView. + + The QAbstractItemModel class provides an interface that is flexible + enough to support data sources that arrange information in hierarchical + structures, allowing for the possibility that data will be inserted, + removed, modified, or sorted in some way. It also provides support for + drag and drop operations. + + The QAbstractListModel and QAbstractTableModel classes provide support + for interfaces to simpler non-hierarchical data structures, and are + easier to use as a starting point for simple list and table models. + + In this section, we create a simple read-only model to explore + the basic principles of the model/view architecture. Later in this + section, we adapt this simple model so that items can be modified + by the user. + + For an example of a more complex model, see the + \l{itemviews/simpletreemodel}{Simple Tree Model} example. + + The requirements of QAbstractItemModel subclasses is described in more + detail in the \l{Model Subclassing Reference} document. + + \section2 Designing a model + + When creating a new model for an existing data structure, it is + important to consider which type of model should be used to + provide an interface onto the data. If the data structure can be + represented as a list or table of items, you can subclass + QAbstractListModel or QAbstractTableModel since these classes + provide suitable default implementations for many functions. + + However, if the underlying data structure can only be represented + by a hierarchical tree structure, it is necessary to subclass + QAbstractItemModel. This approach is taken in the + \l{itemviews/simpletreemodel}{Simple Tree Model} example. + + In this section, we implement a simple model based on a list of + strings, so the QAbstractListModel provides an ideal base class on + which to build. + + Whatever form the underlying data structure takes, it is + usually a good idea to supplement the standard QAbstractItemModel API + in specialized models with one that allows more natural access to the + underlying data structure. This makes it easier to populate the model + with data, yet still enables other general model/view components to + interact with it using the standard API. The model described below + provides a custom constructor for just this purpose. + + \section2 A read-only example model + + The model implemented here is a simple, non-hierarchical, read-only data + model based on the standard QStringListModel class. It has a \l QStringList + as its internal data source, and implements only what is needed to make a + functioning model. To make the implementation easier, we subclass + \l QAbstractListModel because it defines sensible default behavior for list + models, and it exposes a simpler interface than the \l QAbstractItemModel + class. + + When implementing a model it is important to remember that + \l QAbstractItemModel does not store any data itself, it merely + presents an interface that the views use to access the data. + For a minimal read-only model it is only necessary to implement a few + functions as there are default implementations for most of the + interface. The class declaration is as follows: + + \snippet stringlistmodel/model.h 0 + \snippet stringlistmodel/model.h 1 + \codeline + \snippet stringlistmodel/model.h 5 + + Apart from the model's constructor, we only need to implement two + functions: \l{QAbstractItemModel::rowCount()}{rowCount()} returns the + number of rows in the model and \l{QAbstractItemModel::data()}{data()} + returns an item of data corresponding to a specified model index. + + Well behaved models also implement + \l{QAbstractItemModel::headerData()}{headerData()} to give tree and + table views something to display in their headers. + + Note that this is a non-hierarchical model, so we don't have to worry + about the parent-child relationships. If our model was hierarchical, we + would also have to implement the + \l{QAbstractItemModel::index()}{index()} and + \l{QAbstractItemModel::parent()}{parent()} functions. + + The list of strings is stored internally in the \c stringList private + member variable. + + \section3 Dimensions of the model + + We want the number of rows in the model to be the same as the number of + strings in the string list. We implement the + \l{QAbstractItemModel::rowCount()}{rowCount()} function with this in + mind: + + \snippet stringlistmodel/model.cpp 0 + + Since the model is non-hierarchical, we can safely ignore the model index + corresponding to the parent item. By default, models derived from + QAbstractListModel only contain one column, so we do not need to + reimplement the \l{QAbstractItemModel::columnCount()}{columnCount()} + function. + + \section3 Model headers and data + + For items in the view, we want to return the strings in the string list. + The \l{QAbstractItemModel::data()}{data()} function is responsible for + returning the item of data that corresponds to the index argument: + + \snippet stringlistmodel/model.cpp 1-data-read-only + + We only return a valid QVariant if the model index supplied is valid, + the row number is within the range of items in the string list, and the + requested role is one that we support. + + Some views, such as QTreeView and QTableView, are able to display headers + along with the item data. If our model is displayed in a view with headers, + we want the headers to show the row and column numbers. We can provide + information about the headers by subclassing the + \l{QAbstractItemModel::headerData()}{headerData()} function: + + \snippet stringlistmodel/model.cpp 2 + + Again, we return a valid QVariant only if the role is one that we support. + The orientation of the header is also taken into account when deciding the + exact data to return. + + Not all views display headers with the item data, and those that do may + be configured to hide them. Nonetheless, it is recommended that you + implement the \l{QAbstractItemModel::headerData()}{headerData()} function + to provide relevant information about the data provided by the model. + + An item can have several roles, giving out different data depending on the + role specified. The items in our model only have one role, + \l{Qt::ItemDataRole}{DisplayRole}, so we return the data + for items irrespective of the role specified. + However, we could reuse the data we provide for the + \l{Qt::ItemDataRole}{DisplayRole} in + other roles, such as the + \l{Qt::ItemDataRole}{ToolTipRole} that views can use to + display information about items in a tooltip. + + \section2 An editable model + + The read-only model shows how simple choices could be presented to the + user but, for many applications, an editable list model is much more + useful. We can modify the read-only model to make the items editable + by changing the data() function we implemented for read-only, and + by implementing two extra functions: + \l{QAbstractItemModel::flags()}{flags()} and + \l{QAbstractItemModel::setData()}{setData()}. + The following function declarations are added to the class definition: + + \snippet stringlistmodel/model.h 2 + \snippet stringlistmodel/model.h 3 + + \section3 Making the model editable + + A delegate checks whether an item is editable before creating an + editor. The model must let the delegate know that its items are + editable. We do this by returning the correct flags for each item in + the model; in this case, we enable all items and make them both + selectable and editable: + + \snippet stringlistmodel/model.cpp 3 + + Note that we do not have to know how the delegate performs the actual + editing process. We only have to provide a way for the delegate to set the + data in the model. This is achieved through the + \l{QAbstractItemModel::setData()}{setData()} function: + + \snippet stringlistmodel/model.cpp 4 + \snippet stringlistmodel/model.cpp 5 + + In this model, the item in the string list that corresponds to the + model index is replaced by the value provided. However, before we + can modify the string list, we must make sure that the index is + valid, the item is of the correct type, and that the role is + supported. By convention, we insist that the role is the + \l{Qt::ItemDataRole}{EditRole} since this is the role used by the + standard item delegate. For boolean values, however, you can use + Qt::CheckStateRole and set the Qt::ItemIsUserCheckable flag; a + checkbox is then used for editing the value. The underlying + data in this model is the same for all roles, so this detail just + makes it easier to integrate the model with standard components. + + When the data has been set, the model must let the views know that some + data has changed. This is done by emitting the + \l{QAbstractItemModel::dataChanged()}{dataChanged()} signal. Since only + one item of data has changed, the range of items specified in the signal + is limited to just one model index. + + Also the data() function needs to be changed to add the Qt::EditRole test: + + \snippet stringlistmodel/model.cpp 1 + + \section3 Inserting and removing rows + + It is possible to change the number of rows and columns in a model. In the + string list model it only makes sense to change the number of rows, so we + only reimplement the functions for inserting and removing rows. These are + declared in the class definition: + + \snippet stringlistmodel/model.h 4 + + Since rows in this model correspond to strings in a list, the + \c insertRows() function inserts a number of empty strings into the string + list before the specified position. The number of strings inserted is + equivalent to the number of rows specified. + + The parent index is normally used to determine where in the model the + rows should be added. In this case, we only have a single top-level list + of strings, so we just insert empty strings into that list. + + \snippet stringlistmodel/model.cpp 6 + \snippet stringlistmodel/model.cpp 7 + + The model first calls the + \l{QAbstractItemModel::beginInsertRows()}{beginInsertRows()} function to + inform other components that the number of rows is about to change. The + function specifies the row numbers of the first and last new rows to be + inserted, and the model index for their parent item. After changing the + string list, it calls + \l{QAbstractItemModel::endInsertRows()}{endInsertRows()} to complete the + operation and inform other components that the dimensions of the model + have changed, returning true to indicate success. + + The function to remove rows from the model is also simple to write. + The rows to be removed from the model are specified by the position and + the number of rows given. + We ignore the parent index to simplify our implementation, and just + remove the corresponding items from the string list. + + \snippet stringlistmodel/model.cpp 8 + \snippet stringlistmodel/model.cpp 9 + + The \l{QAbstractItemModel::beginRemoveRows()}{beginRemoveRows()} function + is always called before any underlying data is removed, and specifies the + first and last rows to be removed. This allows other components to access + the data before it becomes unavailable. + After the rows have been removed, the model emits + \l{QAbstractItemModel::endRemoveRows()}{endRemoveRows()} to finish the + operation and let other components know that the dimensions of the model + have changed. + + \section2 Next steps + + We can display the data provided by this model, or any other model, using + the \l QListView class to present the model's items in the form of a vertical + list. + For the string list model, this view also provides a default editor so that + the items can be manipulated. We examine the possibilities made available by + the standard view classes in \l{View Classes}. + + The \l{Model Subclassing Reference} document discusses the requirements of + QAbstractItemModel subclasses in more detail, and provides a guide to the + virtual functions that must be implemented to enable various features in + different types of models. + + \section1 Item view convenience classes + + Qt 4 also introduced some standard widgets to provide classic + item-based container widgets. These behave in a similar way to the + item view classes in Qt 3, but have been rewritten to use the + underlying model/view framework for performance and + maintainability. The old item view classes are still available in + the compatibility library (see the \l{porting4.html}{Porting + Guide} for more information). + + The item-based widgets have been given names which reflect their uses: + \c QListWidget provides a list of items, \c QTreeWidget displays a + multi-level tree structure, and \c QTableWidget provides a table of cell + items. Each class inherits the behavior of the \c QAbstractItemView + class which implements common behavior for item selection and header + management. + + \section2 List widgets + + Single level lists of items are typically displayed using a \c QListWidget + and a number of \c{QListWidgetItem}s. A list widget is constructed in the + same way as any other widget: + + \snippet qlistwidget-using/mainwindow.cpp 0 + + List items can be added directly to the list widget when they are + constructed: + + \snippet qlistwidget-using/mainwindow.cpp 3 + + They can also be constructed without a parent list widget and added to + a list at some later time: + + \snippet qlistwidget-using/mainwindow.cpp 6 + \snippet qlistwidget-using/mainwindow.cpp 7 + + Each item in a list can display a text label and an icon. The colors + and font used to render the text can be changed to provide a customized + appearance for items. Tooltips, status tips, and "What's + This?" help are all easily configured to ensure that the list is properly + integrated into the application. + + \snippet qlistwidget-using/mainwindow.cpp 8 + + By default, items in a list are presented in the order of their creation. + Lists of items can be sorted according to the criteria given in + \l{Qt::SortOrder} to produce a list of items that is sorted in forward or + reverse alphabetical order: + + \snippet qlistwidget-using/mainwindow.cpp 4 + \snippet qlistwidget-using/mainwindow.cpp 5 + + \section2 Tree widgets + + Trees or hierarchical lists of items are provided by the \c QTreeWidget + and \c QTreeWidgetItem classes. Each item in the tree widget can have + child items of its own, and can display a number of columns of + information. Tree widgets are created just like any other widget: + + \snippet qtreewidget-using/mainwindow.cpp 0 + + Before items can be added to the tree widget, the number of columns must + be set. For example, we could define two columns, and create a header + to provide labels at the top of each column: + + \snippet qtreewidget-using/mainwindow.cpp 1 + \snippet qtreewidget-using/mainwindow.cpp 2 + + The easiest way to set up the labels for each section is to supply a string + list. For more sophisticated headers, you can construct a tree item, + decorate it as you wish, and use that as the tree widget's header. + + Top-level items in the tree widget are constructed with the tree widget as + their parent widget. They can be inserted in an arbitrary order, or you + can ensure that they are listed in a particular order by specifying the + previous item when constructing each item: + + \snippet qtreewidget-using/mainwindow.cpp 3 + \codeline + \snippet qtreewidget-using/mainwindow.cpp 4 + + Tree widgets deal with top-level items slightly differently to other + items from deeper within the tree. Items can be removed from the top + level of the tree by calling the tree widget's + \l{QTreeWidget::takeTopLevelItem()}{takeTopLevelItem()} function, but + items from lower levels are removed by calling their parent item's + \l{QTreeWidgetItem::takeChild()}{takeChild()} function. + Items are inserted in the top level of the tree with the + \l{QTreeWidget::insertTopLevelItem()}{insertTopLevelItem()} function. + At lower levels in the tree, the parent item's + \l{QTreeWidgetItem::insertChild()}{insertChild()} function is used. + + It is easy to move items around between the top level and lower levels + in the tree. We just need to check whether the items are top-level items + or not, and this information is supplied by each item's \c parent() + function. For example, we can remove the current item in the tree widget + regardless of its location: + + \snippet qtreewidget-using/mainwindow.cpp 10 + \snippet qtreewidget-using/mainwindow.cpp 11 + + Inserting the item somewhere else in the tree widget follows the same + pattern: + + \snippet qtreewidget-using/mainwindow.cpp 8 + \snippet qtreewidget-using/mainwindow.cpp 9 + + \section2 Table widgets + + Tables of items similar to those found in spreadsheet applications + are constructed with the \c QTableWidget and \c QTableWidgetItem. These + provide a scrolling table widget with headers and items to use within it. + + Tables can be created with a set number of rows and columns, or these + can be added to an unsized table as they are needed. + + \snippet qtablewidget-using/mainwindow.h 0 + \snippet qtablewidget-using/mainwindow.cpp 0 + + Items are constructed outside the table before being added to the table + at the required location: + + \snippet qtablewidget-using/mainwindow.cpp 3 + + Horizontal and vertical headers can be added to the table by constructing + items outside the table and using them as headers: + + \snippet qtablewidget-using/mainwindow.cpp 1 + + Note that the rows and columns in the table begin at zero. + + \section2 Common features + + There are a number of item-based features common to each of the + convenience classes that are available through the same interfaces + in each class. We present these in the following sections with some + examples for different widgets. + Look at the list of \l{Model/View Classes} for each of the widgets + for more details about the use of each function used. + + \section3 Hidden items + + It is sometimes useful to be able to hide items in an item view widget + rather than remove them. Items for all of the above widgets can be + hidden and later shown again. You can determine whether an item is hidden + by calling the isItemHidden() function, and items can be hidden with + \c setItemHidden(). + + Since this operation is item-based, the same function is available for + all three convenience classes. + + \section3 Selections + + The way items are selected is controlled by the widget's selection mode + (\l{QAbstractItemView::SelectionMode}). + This property controls whether the user can select one or many items and, + in many-item selections, whether the selection must be a continuous range + of items. The selection mode works in the same way for all of the + above widgets. + + \table + \row + \li \image selection-single.png + \li \b{Single item selections:} + Where the user needs to choose a single item from a widget, the + default \c SingleSelection mode is most suitable. In this mode, the + current item and the selected item are the same. + + \row + \li \image selection-multi.png + \li \b{Multi-item selections:} + In this mode, the user can toggle the selection state of any item in the + widget without changing the existing selection, much like the way + non-exclusive checkboxes can be toggled independently. + + \row + \li \image selection-extended.png + \li \b{Extended selections:} + Widgets that often require many adjacent items to be selected, such + as those found in spreadsheets, require the \c ExtendedSelection mode. + In this mode, continuous ranges of items in the widget can be selected + with both the mouse and the keyboard. + Complex selections, involving many items that are not adjacent to other + selected items in the widget, can also be created if modifier keys are + used. + + If the user selects an item without using a modifier key, the existing + selection is cleared. + \endtable + + The selected items in a widget are read using the \c selectedItems() + function, providing a list of relevant items that can be iterated over. + For example, we can find the sum of all the numeric values within a + list of selected items with the following code: + + \snippet qtablewidget-using/mainwindow.cpp 4 + + Note that for the single selection mode, the current item will be in + the selection. In the multi-selection and extended selection modes, the + current item may not lie within the selection, depending on the way the + user formed the selection. + + \section3 Searching + + It is often useful to be able to find items within an item view widget, + either as a developer or as a service to present to users. All three + item view convenience classes provide a common \c findItems() function + to make this as consistent and simple as possible. + + Items are searched for by the text that they contain according to + criteria specified by a selection of values from Qt::MatchFlags. + We can obtain a list of matching items with the \c findItems() + function: + + \snippet qtreewidget-using/mainwindow.cpp 6 + \snippet qtreewidget-using/mainwindow.cpp 7 + + The above code causes items in a tree widget to be selected if they + contain the text given in the search string. This pattern can also be + used in the list and table widgets. + + \section1 Using Drag and Drop with Item Views + + Qt's drag and drop infrastructure is fully supported by the model/view framework. + Items in lists, tables, and trees can be dragged within the views, and data can be + imported and exported as MIME-encoded data. + + The standard views automatically support internal drag and drop, where items are + moved around to change the order in which they are displayed. By default, drag and + drop is not enabled for these views because they are configured for the simplest, + most common uses. To allow items to be dragged around, certain properties of the + view need to be enabled, and the items themselves must also allow dragging to occur. + + The requirements for a model that only allows items to be exported from a + view, and which does not allow data to be dropped into it, are fewer than + those for a fully-enabled drag and drop model. + + See also the \l{Model Subclassing Reference} for more information about + enabling drag and drop support in new models. + + \section2 Using convenience views + + Each of the types of item used with QListWidget, QTableWidget, and QTreeWidget + is configured to use a different set of flags by default. For example, each + QListWidgetItem or QTreeWidgetItem is initially enabled, checkable, selectable, + and can be used as the source of a drag and drop operation; each QTableWidgetItem + can also be edited and used as the target of a drag and drop operation. + + Although all of the standard items have one or both flags set for drag and drop, + you generally need to set various properties in the view itself to take advantage + of the built-in support for drag and drop: + + \list + \li To enable item dragging, set the view's + \l{QAbstractItemView::dragEnabled}{dragEnabled} property to \c true. + \li To allow the user to drop either internal or external items within the view, + set the view's \l{QAbstractScrollArea::}{viewport()}'s + \l{QWidget::acceptDrops}{acceptDrops} property to \c true. + \li To show the user where the item currently being dragged will be placed if + dropped, set the view's \l{QAbstractItemView::showDropIndicator}{showDropIndicator} + property. This provides the user with continuously updating information about + item placement within the view. + \endlist + + For example, we can enable drag and drop in a list widget with the following lines + of code: + + \snippet qlistwidget-dnd/mainwindow.cpp 0 + + The result is a list widget which allows the items to be copied + around within the view, and even lets the user drag items between + views containing the same type of data. In both situations, the + items are copied rather than moved. + + To enable the user to move the items around within the view, we + must set the list widget's \l {QAbstractItemView::}{dragDropMode}: + + \snippet qlistwidget-dnd/mainwindow.cpp 1 + + \section2 Using model/view classes + + Setting up a view for drag and drop follows the same pattern used with the + convenience views. For example, a QListView can be set up in the same way as a + QListWidget: + + \snippet qlistview-dnd/mainwindow.cpp 0 + + Since access to the data displayed by the view is controlled by a model, the + model used also has to provide support for drag and drop operations. The + actions supported by a model can be specified by reimplementing the + QAbstractItemModel::supportedDropActions() function. For example, copy and + move operations are enabled with the following code: + + \snippet qlistview-dnd/model.cpp 10 + + Although any combination of values from Qt::DropActions can be given, the + model needs to be written to support them. For example, to allow Qt::MoveAction + to be used properly with a list model, the model must provide an implementation + of QAbstractItemModel::removeRows(), either directly or by inheriting the + implementation from its base class. + + \section3 Enabling drag and drop for items + + Models indicate to views which items can be dragged, and which will accept drops, + by reimplementing the QAbstractItemModel::flags() function to provide suitable + flags. + + For example, a model which provides a simple list based on QAbstractListModel + can enable drag and drop for each of the items by ensuring that the flags + returned contain the \l Qt::ItemIsDragEnabled and \l Qt::ItemIsDropEnabled + values: + + \snippet qlistview-dnd/model.cpp 7 + + Note that items can be dropped into the top level of the model, but dragging is + only enabled for valid items. + + In the above code, since the model is derived from QStringListModel, we + obtain a default set of flags by calling its implementation of the flags() + function. + + \section3 Encoding exported data + + When items of data are exported from a model in a drag and drop operation, they + are encoded into an appropriate format corresponding to one or more MIME types. + Models declare the MIME types that they can use to supply items by reimplementing + the QAbstractItemModel::mimeTypes() function, returning a list of standard MIME + types. + + For example, a model that only provides plain text would provide the following + implementation: + + \snippet qlistview-dnd/model.cpp 9 + + The model must also provide code to encode data in the advertised format. This + is achieved by reimplementing the QAbstractItemModel::mimeData() function to + provide a QMimeData object, just as in any other drag and drop operation. + + The following code shows how each item of data, corresponding to a given list of + indexes, is encoded as plain text and stored in a QMimeData object. + + \snippet qlistview-dnd/model.cpp 8 + + Since a list of model indexes is supplied to the function, this approach is general + enough to be used in both hierarchical and non-heirarchical models. + + Note that custom datatypes must be declared as \l{QMetaObject}{meta objects} + and that stream operators must be implemented for them. See the QMetaObject + class description for details. + + \section3 Inserting dropped data into a model + + The way that any given model handles dropped data depends on both its type + (list, table, or tree) and the way its contents is likely to be presented to + the user. Generally, the approach taken to accommodate dropped data should + be the one that most suits the model's underlying data store. + + Different types of model tend to handle dropped data in different ways. List + and table models only provide a flat structure in which items of data are + stored. As a result, they may insert new rows (and columns) when data is + dropped on an existing item in a view, or they may overwrite the item's + contents in the model using some of the data supplied. Tree models are + often able to add child items containing new data to their underlying data + stores, and will therefore behave more predictably as far as the user + is concerned. + + Dropped data is handled by a model's reimplementation of + QAbstractItemModel::dropMimeData(). For example, a model that handles a + simple list of strings can provide an implementation that handles data + dropped onto existing items separately to data dropped into the top level + of the model (i.e., onto an invalid item). + + The model first has to make sure that the operation should be acted on, + the data supplied is in a format that can be used, and that its destination + within the model is valid: + + \snippet qlistview-dnd/model.cpp 0 + \snippet qlistview-dnd/model.cpp 1 + + A simple one column string list model can indicate failure if the data + supplied is not plain text, or if the column number given for the drop + is invalid. + + The data to be inserted into the model is treated differently depending on + whether it is dropped onto an existing item or not. In this simple example, + we want to allow drops between existing items, before the first item in the + list, and after the last item. + + When a drop occurs, the model index corresponding to the parent item will + either be valid, indicating that the drop occurred on an item, or it will + be invalid, indicating that the drop occurred somewhere in the view that + corresponds to top level of the model. + + \snippet qlistview-dnd/model.cpp 2 + + We initially examine the row number supplied to see if we can use it + to insert items into the model, regardless of whether the parent index is + valid or not. + + \snippet qlistview-dnd/model.cpp 3 + + If the parent model index is valid, the drop occurred on an item. In this + simple list model, we find out the row number of the item and use that + value to insert dropped items into the top level of the model. + + \snippet qlistview-dnd/model.cpp 4 + + When a drop occurs elsewhere in the view, and the row number is unusable, + we append items to the top level of the model. + + In hierarchical models, when a drop occurs on an item, it would be better to + insert new items into the model as children of that item. In the simple + example shown here, the model only has one level, so this approach is not + appropriate. + + \section3 Decoding imported data + + Each implementation of \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} must + also decode the data and insert it into the model's underlying data structure. + + For a simple string list model, the encoded items can be decoded and streamed + into a QStringList: + + \snippet qlistview-dnd/model.cpp 5 + + The strings can then be inserted into the underlying data store. For consistency, + this can be done through the model's own interface: + + \snippet qlistview-dnd/model.cpp 6 + + Note that the model will typically need to provide implementations of the + QAbstractItemModel::insertRows() and QAbstractItemModel::setData() functions. + + \sa {Item Views Puzzle Example} + + \section1 Proxy models + + In the model/view framework, items of data supplied by a single model can be shared + by any number of views, and each of these can possibly represent the same information + in completely different ways. + Custom views and delegates are effective ways to provide radically different + representations of the same data. However, applications often need to provide + conventional views onto processed versions of the same data, such as differently-sorted + views onto a list of items. + + Although it seems appropriate to perform sorting and filtering operations as internal + functions of views, this approach does not allow multiple views to share the results + of such potentially costly operations. The alternative approach, involving sorting + within the model itself, leads to the similar problem where each view has to display + items of data that are organized according to the most recent processing operation. + + To solve this problem, the model/view framework uses proxy models to manage the + information supplied between individual models and views. Proxy models are components + that behave like ordinary models from the perspective of a view, and access data from + source models on behalf of that view. The signals and slots used by the model/view + framework ensure that each view is updated appropriately no matter how many proxy models + are placed between itself and the source model. + + \section2 Using proxy models + + Proxy models can be inserted between an existing model and any number of views. + Qt is supplied with a standard proxy model, QSortFilterProxyModel, that is usually + instantiated and used directly, but can also be subclassed to provide custom filtering + and sorting behavior. The QSortFilterProxyModel class can be used in the following way: + + \snippet qsortfilterproxymodel/main.cpp 0 + \codeline + \snippet qsortfilterproxymodel/main.cpp 1 + + Since proxy models are inherit from QAbstractItemModel, they can be connected to + any kind of view, and can be shared between views. They can also be used to + process the information obtained from other proxy models in a pipeline arrangement. + + The QSortFilterProxyModel class is designed to be instantiated and used directly + in applications. More specialized proxy models can be created by subclassing this + classes and implementing the required comparison operations. + + \section2 Customizing proxy models + + Generally, the type of processing used in a proxy model involves mapping each item of + data from its original location in the source model to either a different location in + the proxy model. In some models, some items may have no corresponding location in the + proxy model; these models are \e filtering proxy models. Views access items using + model indexes provided by the proxy model, and these contain no information about the + source model or the locations of the original items in that model. + + QSortFilterProxyModel enables data from a source model to be filtered before + being supplied to views, and also allows the contents of a source model to + be supplied to views as pre-sorted data. + + \section3 Custom filtering models + + The QSortFilterProxyModel class provides a filtering model that is fairly versatile, + and which can be used in a variety of common situations. For advanced users, + QSortFilterProxyModel can be subclassed, providing a mechanism that enables custom + filters to be implemented. + + Subclasses of QSortFilterProxyModel can reimplement two virtual functions that are + called whenever a model index from the proxy model is requested or used: + + \list + \li \l{QSortFilterProxyModel::filterAcceptsColumn()}{filterAcceptsColumn()} is used to + filter specific columns from part of the source model. + \li \l{QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} is used to filter + specific rows from part of the source model. + \endlist + + The default implementations of the above functions in QSortFilterProxyModel + return true to ensure that all items are passed through to views; reimplementations + of these functions should return false to filter out individual rows and columns. + + \section3 Custom sorting models + + QSortFilterProxyModel instances use Qt's built-in qStableSort() function to set up + mappings between items in the source model and those in the proxy model, allowing a + sorted hierarchy of items to be exposed to views without modifying the structure of the + source model. To provide custom sorting behavior, reimplement the + \l{QSortFilterProxyModel::lessThan()}{lessThan()} function to perform custom + comparisons. + + \section1 Model subclassing reference + + Model subclasses need to provide implementations of many of the virtual functions + defined in the QAbstractItemModel base class. The number of these functions that need + to be implemented depends on the type of model - whether it supplies views with + a simple list, a table, or a complex hierarchy of items. Models that inherit from + QAbstractListModel and QAbstractTableModel can take advantage of the default + implementations of functions provided by those classes. Models that expose items + of data in tree-like structures must provide implementations for many of the + virtual functions in QAbstractItemModel. + + The functions that need to be implemented in a model subclass can be divided into three + groups: + + \list + \li \b{Item data handling:} All models need to implement functions to enable views and + delegates to query the dimensions of the model, examine items, and retrieve data. + \li \b{Navigation and index creation:} Hierarchical models need to provide functions + that views can call to navigate the tree-like structures they expose, and obtain + model indexes for items. + \li \b{Drag and drop support and MIME type handling:} Models inherit functions that + control the way that internal and external drag and drop operations are performed. + These functions allow items of data to be described in terms of MIME types that + other components and applications can understand. + \endlist + + For more information, see the \l + {"Item View Classes" Chapter of C++ GUI Programming with Qt 4}. + + \section2 Item data handling + + Models can provide varying levels of access to the data they provide: They can be + simple read-only components, some models may support resizing operations, and + others may allow items to be edited. + + \section2 Read-Only access + + To provide read-only access to data provided by a model, the following functions + \e{must} be implemented in the model's subclass: + + \table 90% + \row \li \l{QAbstractItemModel::flags()}{flags()} + \li Used by other components to obtain information about each item provided by + the model. In many models, the combination of flags should include + Qt::ItemIsEnabled and Qt::ItemIsSelectable. + \row \li \l{QAbstractItemModel::data()}{data()} + \li Used to supply item data to views and delegates. Generally, models only + need to supply data for Qt::DisplayRole and any application-specific user + roles, but it is also good practice to provide data for Qt::ToolTipRole, + Qt::AccessibleTextRole, and Qt::AccessibleDescriptionRole. + See the Qt::ItemDataRole enum documentation for information about the types + associated with each role. + \row \li \l{QAbstractItemModel::headerData()}{headerData()} + \li Provides views with information to show in their headers. The information is + only retrieved by views that can display header information. + \row \li \l{QAbstractItemModel::rowCount()}{rowCount()} + \li Provides the number of rows of data exposed by the model. + \endtable + + These four functions must be implemented in all types of model, including list models + (QAbstractListModel subclasses) and table models (QAbstractTableModel subclasses). + + Additionally, the following functions \e{must} be implemented in direct subclasses + of QAbstractTableModel and QAbstractItemModel: + + \table 90% + \row \li \l{QAbstractItemModel::columnCount()}{columnCount()} + \li Provides the number of columns of data exposed by the model. List models do not + provide this function because it is already implemented in QAbstractListModel. + \endtable + + \section3 Editable items + + Editable models allow items of data to be modified, and may also provide + functions to allow rows and columns to be inserted and removed. To enable + editing, the following functions must be implemented correctly: + + \table 90% + \row \li \l{QAbstractItemModel::flags()}{flags()} + \li Must return an appropriate combination of flags for each item. In particular, + the value returned by this function must include \l{Qt::ItemIsEditable} in + addition to the values applied to items in a read-only model. + \row \li \l{QAbstractItemModel::setData()}{setData()} + \li Used to modify the item of data associated with a specified model index. + To be able to accept user input, provided by user interface elements, this + function must handle data associated with Qt::EditRole. + The implementation may also accept data associated with many different kinds + of roles specified by Qt::ItemDataRole. After changing the item of data, + models must emit the \l{QAbstractItemModel::dataChanged()}{dataChanged()} + signal to inform other components of the change. + \row \li \l{QAbstractItemModel::setHeaderData()}{setHeaderData()} + \li Used to modify horizontal and vertical header information. After changing + the item of data, models must emit the + \l{QAbstractItemModel::headerDataChanged()}{headerDataChanged()} + signal to inform other components of the change. + \endtable + + \section3 Resizable models + + All types of model can support the insertion and removal of rows. Table models + and hierarchical models can also support the insertion and removal of columns. + It is important to notify other components about changes to the model's dimensions + both \e before and \e after they occur. As a result, the following functions + can be implemented to allow the model to be resized, but implementations must + ensure that the appropriate functions are called to notify attached views and + delegates: + + \table 90% + \row \li \l{QAbstractItemModel::insertRows()}{insertRows()} + \li Used to add new rows and items of data to all types of model. + Implementations must call + \l{QAbstractItemModel::beginInsertRows()}{beginInsertRows()} \e before + inserting new rows into any underlying data structures, and call + \l{QAbstractItemModel::endInsertRows()}{endInsertRows()} + \e{immediately afterwards}. + \row \li \l{QAbstractItemModel::removeRows()}{removeRows()} + \li Used to remove rows and the items of data they contain from all types of model. + Implementations must call + \l{QAbstractItemModel::beginRemoveRows()}{beginRemoveRows()} + \e before inserting new columns into any underlying data structures, and call + \l{QAbstractItemModel::endRemoveRows()}{endRemoveRows()} + \e{immediately afterwards}. + \row \li \l{QAbstractItemModel::insertColumns()}{insertColumns()} + \li Used to add new columns and items of data to table models and hierarchical models. + Implementations must call + \l{QAbstractItemModel::beginInsertColumns()}{beginInsertColumns()} \e before + rows are removed from any underlying data structures, and call + \l{QAbstractItemModel::endInsertColumns()}{endInsertColumns()} + \e{immediately afterwards}. + \row \li \l{QAbstractItemModel::removeColumns()}{removeColumns()} + \li Used to remove columns and the items of data they contain from table models and + hierarchical models. + Implementations must call + \l{QAbstractItemModel::beginRemoveColumns()}{beginRemoveColumns()} + \e before columns are removed from any underlying data structures, and call + \l{QAbstractItemModel::endRemoveColumns()}{endRemoveColumns()} + \e{immediately afterwards}. + \endtable + + Generally, these functions should return true if the operation was successful. + However, there may be cases where the operation only partly succeeded; for example, + if less than the specified number of rows could be inserted. In such cases, the + model should return false to indicate failure to enable any attached components to + handle the situation. + + The signals emitted by the functions called in implementations of the resizing + API give attached components the chance to take action before any data becomes + unavailable. The encapsulation of insert and remove operations with begin and end + functions also enable the model to manage + \l{QPersistentModelIndex}{persistent model indexes} correctly. + + Normally, the begin and end functions are capable of informing other components + about changes to the model's underlying structure. For more complex changes to the + model's structure, perhaps involving internal reorganization or sorting of data, + it is necessary to emit the \l{QAbstractItemModel::layoutChanged()}{layoutChanged()} + signal to cause any attached views to be updated. + + \section3 Lazy population of model data + + Lazy population of model data effectively allows requests for information + about the model to be deferred until it is actually needed by views. + + Some models need to obtain data from remote sources, or must perform + time-consuming operations to obtain information about the way the + data is organized. Since views generally request as much information + as possible in order to accurately display model data, it can be useful + to restrict the amount of information returned to them to reduce + unnecessary follow-up requests for data. + + In hierarchical models where finding the number of children of a given + item is an expensive operation, it is useful to ensure that the model's + \l{QAbstractItemModel::}{rowCount()} implementation is only called when + necessary. In such cases, the \l{QAbstractItemModel::}{hasChildren()} + function can be reimplemented to provide an inexpensive way for views to + check for the presence of children and, in the case of QTreeView, draw + the appropriate decoration for their parent item. + + Whether the reimplementation of \l{QAbstractItemModel::}{hasChildren()} + returns \c true or \c false, it may not be necessary for the view to call + \l{QAbstractItemModel::}{rowCount()} to find out how many children are + present. For example, QTreeView does not need to know how many children + there are if the parent item has not been expanded to show them. + + If it is known that many items will have children, reimplementing + \l{QAbstractItemModel::}{hasChildren()} to unconditionally return \c true + is sometimes a useful approach to take. This ensures that each item can + be later examined for children while making initial population of model + data as fast as possible. The only disadvantage is that items without + children may be displayed incorrectly in some views until the user + attempts to view the non-existent child items. + + \section2 Navigation and model index creation + + Hierarchical models need to provide functions that views can call to navigate the + tree-like structures they expose, and obtain model indexes for items. + + \section3 Parents and children + + Since the structure exposed to views is determined by the underlying data + structure, it is up to each model subclass to create its own model indexes + by providing implementations of the following functions: + + \table 90% + \row \li \l{QAbstractItemModel::index()}{index()} + \li Given a model index for a parent item, this function allows views and delegates + to access children of that item. If no valid child item - corresponding to the + specified row, column, and parent model index, can be found, the function + must return QModelIndex(), which is an invalid model index. + \row \li \l{QAbstractItemModel::parent()}{parent()} + \li Provides a model index corresponding to the parent of any given child item. + If the model index specified corresponds to a top-level item in the model, or if + there is no valid parent item in the model, the function must return + an invalid model index, created with the empty QModelIndex() constructor. + \endtable + + Both functions above use the \l{QAbstractItemModel::createIndex()}{createIndex()} + factory function to generate indexes for other components to use. It is normal for + models to supply some unique identifier to this function to ensure that + the model index can be re-associated with its corresponding item later on. + + \section2 Drag and drop support and MIME type handling + + The model/view classes support drag and drop operations, providing default behavior + that is sufficient for many applications. However, it is also possible to customize + the way items are encoded during drag and drop operations, whether they are copied + or moved by default, and how they are inserted into existing models. + + Additionally, the convenience view classes implement specialized behavior that + should closely follow that expected by existing developers. + The \l{#Convenience Views}{Convenience Views} section provides an overview of this + behavior. + + \section3 MIME data + + By default, the built-in models and views use an internal MIME type + (\c{application/x-qabstractitemmodeldatalist}) to pass around information about + model indexes. This specifies data for a list of items, containing the row and + column numbers of each item, and information about the roles that each item + supports. + + Data encoded using this MIME type can be obtained by calling + QAbstractItemModel::mimeData() with a QModelIndexList containing the items to + be serialized. + \omit + The following types are used to store information about + each item as it is streamed into a QByteArray and stored in a QMimeData object: + + \table 90% + \header \li Description \li Type + \row \li Row \li int + \row \li Column \li int + \row \li Data for each role \li QMap<int, QVariant> + \endtable + + This information can be retrieved for use in non-model classes by calling + QMimeData::data() with the \c{application/x-qabstractitemmodeldatalist} MIME + type and streaming out the items one by one. + \endomit + + When implementing drag and drop support in a custom model, it is possible to + export items of data in specialized formats by reimplementing the following + function: + + \table 90% + \row \li \l{QAbstractItemModel::mimeData()}{mimeData()} + \li This function can be reimplemented to return data in formats other + than the default \c{application/x-qabstractitemmodeldatalist} internal + MIME type. + + Subclasses can obtain the default QMimeData object from the base class + and add data to it in additional formats. + \endtable + + For many models, it is useful to provide the contents of items in common format + represented by MIME types such as \c{text/plain} and \c{image/png}. Note that + images, colors and HTML documents can easily be added to a QMimeData object with + the QMimeData::setImageData(), QMimeData::setColorData(), and + QMimeData::setHtml() functions. + + \section3 Accepting dropped data + + When a drag and drop operation is performed over a view, the underlying model is + queried to determine which types of operation it supports and the MIME types + it can accept. This information is provided by the + QAbstractItemModel::supportedDropActions() and QAbstractItemModel::mimeTypes() + functions. Models that do not override the implementations provided by + QAbstractItemModel support copy operations and the default internal MIME type + for items. + + When serialized item data is dropped onto a view, the data is inserted into + the current model using its implementation of QAbstractItemModel::dropMimeData(). + The default implementation of this function will never overwrite any data in the + model; instead, it tries to insert the items of data either as siblings of an + item, or as children of that item. + + To take advantage of QAbstractItemModel's default implementation for the built-in + MIME type, new models must provide reimplementations of the following functions: + + \table 90% + \row \li \l{QAbstractItemModel::insertRows()}{insertRows()} + \li {1, 2} These functions enable the model to automatically insert new data using + the existing implementation provided by QAbstractItemModel::dropMimeData(). + \row \li \l{QAbstractItemModel::insertColumns()}{insertColumns()} + \row \li \l{QAbstractItemModel::setData()}{setData()} + \li Allows the new rows and columns to be populated with items. + \row \li \l{QAbstractItemModel::setItemData()}{setItemData()} + \li This function provides more efficient support for populating new items. + \endtable + + To accept other forms of data, these functions must be reimplemented: + + \table 90% + \row \li \l{QAbstractItemModel::supportedDropActions()}{supportedDropActions()} + \li Used to return a combination of \l{Qt::DropActions}{drop actions}, + indicating the types of drag and drop operations that the model accepts. + \row \li \l{QAbstractItemModel::mimeTypes()}{mimeTypes()} + \li Used to return a list of MIME types that can be decoded and handled by + the model. Generally, the MIME types that are supported for input into + the model are the same as those that it can use when encoding data for + use by external components. + \row \li \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} + \li Performs the actual decoding of the data transferred by drag and drop + operations, determines where in the model it will be set, and inserts + new rows and columns where necessary. How this function is implemented + in subclasses depends on the requirements of the data exposed by each + model. + \endtable + + If the implementation of the \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} + function changes the dimensions of a model by inserting or removing rows or + columns, or if items of data are modified, care must be taken to ensure that + all relevant signals are emitted. It can be useful to simply call + reimplementations of other functions in the subclass, such as + \l{QAbstractItemModel::setData()}{setData()}, + \l{QAbstractItemModel::insertRows()}{insertRows()}, and + \l{QAbstractItemModel::insertColumns()}{insertColumns()}, to ensure that the + model behaves consistently. + + In order to ensure drag operations work properly, it is important to + reimplement the following functions that remove data from the model: + + \list + \li \l{QAbstractItemModel::}{removeRows()} + \li \l{QAbstractItemModel::}{removeRow()} + \li \l{QAbstractItemModel::}{removeColumns()} + \li \l{QAbstractItemModel::}{removeColumn()} + \endlist + + For more information about drag and drop with item views, refer to + \l{Using drag and drop with item views}. + + \section3 Convenience views + + The convenience views (QListWidget, QTableWidget, and QTreeWidget) override + the default drag and drop functionality to provide less flexible, but more + natural behavior that is appropriate for many applications. For example, + since it is more common to drop data into cells in a QTableWidget, replacing + the existing contents with the data being transferred, the underlying model + will set the data of the target items rather than insert new rows and columns + into the model. For more information on drag and drop in convenience views, + you can see \l{Using drag and drop with item views}. + + \section2 Performance optimization for large amounts of data + + The \l{QAbstractItemModel::}{canFetchMore()} function checks if the parent + has more data available and returns true or false accordingly. The + \l{QAbstractItemModel::}{fetchMore()} function fetches data based on the + parent specified. Both these functions can be combined, for example, in a + database query involving incremental data to populate a QAbstractItemModel. + We reimplement \l{QAbstractItemModel::}{canFetchMore()} to indicate if there + is more data to be fetched and \l{QAbstractItemModel::}{fetchMore()} to + populate the model as required. + + Another example would be dynamically populated tree models, where we + reimplement \l{QAbstractItemModel::}{fetchMore()} when a branch in the tree + model is expanded. + + If your reimplementation of \l{QAbstractItemModel::}{fetchMore()} adds rows + to the model, you need to call \l{QAbstractItemModel::}{beginInsertRows()} + and \l{QAbstractItemModel::}{endInsertRows()}. Also, both + \l{QAbstractItemModel::}{canFetchMore()} and \l{QAbstractItemModel::} + {fetchMore()} must be reimplemented as their default implementation returns + false and does nothing. + + \keyword Model/View Classes + \section1 The model/view classes + + These classes use the model/view design pattern in which the + underlying data (in the model) is kept separate from the way the + data is presented and manipulated by the user (in the view). + + \annotatedlist model-view + + \section1 Related examples + + \list + \li \l{itemviews/dirview}{Dir View} + \li \l{itemviews/spinboxdelegate}{Spin Box Delegate} + \li \l{itemviews/pixelator}{Pixelator} + \li \l{itemviews/simpletreemodel}{Simple Tree Model} + \li \l{itemviews/chart}{Chart} + \endlist +*/ diff --git a/doc/src/widgets/modelview.qdoc b/src/widgets/doc/src/modelview.qdoc index fdd25def31..97432b4df4 100644 --- a/doc/src/widgets/modelview.qdoc +++ b/src/widgets/doc/src/modelview.qdoc @@ -201,7 +201,7 @@ add editing capabilities later. (file source: examples/tutorials/modelview/1_readonly/main.cpp) - \snippet examples/tutorials/modelview/1_readonly/main.cpp Quoting ModelView Tutorial + \snippet tutorials/modelview/1_readonly/main.cpp Quoting ModelView Tutorial We have the usual \l {modelview-part2-main-cpp.html}{main()} function: @@ -222,12 +222,12 @@ is easier to use than the more general QAbstractItemModel. (file source: examples/tutorials/modelview/1_readonly/mymodel.h) - \snippet examples/tutorials/modelview/1_readonly/mymodel.h Quoting ModelView Tutorial + \snippet tutorials/modelview/1_readonly/mymodel.h Quoting ModelView Tutorial QAbstractTableModel requires the implementation of three abstract methods. (file source: examples/tutorials/modelview/1_readonly/mymodel.cpp) - \snippet examples/tutorials/modelview/1_readonly/mymodel.cpp Quoting ModelView Tutorial + \snippet tutorials/modelview/1_readonly/mymodel.cpp Quoting ModelView Tutorial The number of rows and columns is provided by \l{QAbstractItemModel::rowCount()}{MyModel::rowCount()} and @@ -263,7 +263,7 @@ role to return different pieces of information depending on its value. (file source: examples/tutorials/modelview/2_formatting/mymodel.cpp) - \snippet examples/tutorials/modelview/2_formatting/mymodel.cpp Quoting ModelView Tutorial + \snippet tutorials/modelview/2_formatting/mymodel.cpp Quoting ModelView Tutorial Each formatting property will be requested from the model with a separate call to the \l{QAbstractItemModel::data()}{data()} method. The \c role @@ -311,7 +311,7 @@ stream. In our small example, \l{QAbstractItemModel::}{data()} will be called 42 times. Each time you hover the cursor over the field, - \l{QAbstractItemModel::}{data()} will be called again \mdash 7 times for + \l{QAbstractItemModel::}{data()} will be called again -- 7 times for each cell. That's why it is important to make sure that your data is available when \l{QAbstractItemModel::}{data()} is invoked and expensive lookup operations are cached. @@ -324,7 +324,7 @@ second because we are showing the current time. (file source: examples/tutorials/modelview/3_changingmodel/mymodel.cpp) - \snippet examples/tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_QVariant + \snippet tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_QVariant Something is missing to make the clock tick. We need to tell the view every second that the time has changed and that it needs to be read again. We do @@ -332,12 +332,12 @@ connect its timeout signal. (file source: examples/tutorials/modelview/3_changingmodel/mymodel.cpp) - \snippet examples/tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_a + \snippet tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_a Here is the corresponding slot: (file source: examples/tutorials/modelview/3_changingmodel/mymodel.cpp) - \snippet examples/tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_b + \snippet tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_b We ask the view to read the data in the top left cell again by emitting the \l{QAbstractItemModel::}{dataChanged()} signal. Note that we did not @@ -353,7 +353,7 @@ \l{QAbstractItemModel::headerData()}{headerData()} method: (file source: examples/tutorials/modelview/4_headers/mymodel.cpp) - \snippet examples/tutorials/modelview/4_headers/mymodel.cpp quoting mymodel_c + \snippet tutorials/modelview/4_headers/mymodel.cpp quoting mymodel_c Note that method \l{QAbstractItemModel::headerData()}{headerData()} also has a parameter role which has the same meaning as in @@ -372,7 +372,7 @@ \l{QAbstractItemModel::}{setData()} and \l{QAbstractItemModel::}{flags()}. (file source: examples/tutorials/modelview/5_edit/mymodel.h) - \snippet examples/tutorials/modelview/5_edit/mymodel.h Quoting ModelView Tutorial + \snippet tutorials/modelview/5_edit/mymodel.h Quoting ModelView Tutorial We use \c the two-dimensional array QString \c m_gridData to store our data. This makes \c m_gridData the core of \c MyModel. The rest of \c MyModel acts @@ -381,7 +381,7 @@ makes it possible to transfer the modified text to the window title. (file source: examples/tutorials/modelview/5_edit/mymodel.cpp) - \snippet examples/tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_e + \snippet tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_e \l{QAbstractItemModel::setData()}{setData()} will be called each time the user edits a cell. The \c index parameter tells us which field has been @@ -392,7 +392,7 @@ \l Qt::CheckStateRole. (file source: examples/tutorials/modelview/5_edit/mymodel.cpp) - \snippet examples/tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_f + \snippet tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_f Various properties of a cell can be adjusted with \l{QAbstractItemModel::flags()}{flags()}. @@ -436,7 +436,7 @@ \image tree_2_with_algorithm.png (file source: examples/tutorials/modelview/6_treeview/mainwindow.cpp) - \snippet examples/tutorials/modelview/6_treeview/mainwindow.cpp Quoting ModelView Tutorial + \snippet tutorials/modelview/6_treeview/mainwindow.cpp Quoting ModelView Tutorial We simply instantiate a QStandardItemModel and add a couple of \l{QStandardItem}{QStandardItems} to the constructor. We can then make a @@ -454,7 +454,7 @@ So let's create a couple of items: (file source: examples/tutorials/modelview/7_selections/mainwindow.cpp) - \snippet examples/tutorials/modelview/7_selections/mainwindow.cpp quoting modelview_a + \snippet tutorials/modelview/7_selections/mainwindow.cpp quoting modelview_a Views manage selections within a separate selection model, which can be retrieved with the \l{QAbstractItemView::}{selectionModel()} method. We @@ -462,7 +462,7 @@ \l{QAbstractItemView::}{selectionChanged()} signal. (file source: examples/tutorials/modelview/7_selections/mainwindow.cpp) - \snippet examples/tutorials/modelview/7_selections/mainwindow.cpp quoting modelview_b + \snippet tutorials/modelview/7_selections/mainwindow.cpp quoting modelview_b We get the model index that corresponds to the selection by calling \l{QItemSelectionModel::currentIndex()}{treeView->selectionModel()->currentIndex()} diff --git a/doc/src/widgets/widgets-tutorial.qdoc b/src/widgets/doc/src/widgets-tutorial.qdoc index 735a7ebc54..37f095d500 100644 --- a/doc/src/widgets/widgets-tutorial.qdoc +++ b/src/widgets/doc/src/widgets-tutorial.qdoc @@ -63,7 +63,7 @@ A typical \c main() function in \c{main.cpp} looks like this: - \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body + \snippet widgets-tutorial/template.cpp main.cpp body First, a QApplication object is constructed, which can be configured with arguments passed in from the command line. After diff --git a/doc/src/widgets/windows-and-dialogs/dialogs.qdoc b/src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc index e1c6de42b8..e1c6de42b8 100644 --- a/doc/src/widgets/windows-and-dialogs/dialogs.qdoc +++ b/src/widgets/doc/src/windows-and-dialogs/dialogs.qdoc diff --git a/doc/src/widgets/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc index 3a2efb06a2..3c175669fb 100644 --- a/doc/src/widgets/windows-and-dialogs/mainwindow.qdoc +++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -198,17 +198,17 @@ the first time it is called. You can also call QMainWindow::setMenuBar() to use a custom menu bar in the main window. - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0 + \snippet code/doc_src_qt4-mainwindow.cpp 0 \dots - \snippet examples/mainwindows/menus/mainwindow.cpp 5 + \snippet mainwindows/menus/mainwindow.cpp 5 \dots Once actions have been created, we can add them to the main window components. To begin with, we add them to the pop-up menus: - \snippet examples/mainwindows/menus/mainwindow.cpp 10 + \snippet mainwindows/menus/mainwindow.cpp 10 \dots - \snippet examples/mainwindows/menus/mainwindow.cpp 11 + \snippet mainwindows/menus/mainwindow.cpp 11 \dots The QToolBar and QMenu classes use Qt's action system to provide a @@ -220,9 +220,9 @@ We create a toolbar as a child of the main window, and add the desired actions to it: - \snippet examples/mainwindows/sdi/mainwindow.cpp 0 + \snippet mainwindows/sdi/mainwindow.cpp 0 \dots - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1 + \snippet code/doc_src_qt4-mainwindow.cpp 1 In this example, the toolbar is restricted to the top and bottom toolbar areas of the main window, and is initially placed in the @@ -234,7 +234,7 @@ dock widget as a child of the main window, and add widgets as children of the dock widget: - \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0 + \snippet dockwidgets/mainwindow.cpp 0 In this example, the dock widget can only be placed in the left and right dock areas, and it is initially placed in the left dock area. @@ -244,7 +244,7 @@ required, the default can be changed with the QMainWindow::setCorner() function: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2 + \snippet code/doc_src_qt4-mainwindow.cpp 2 The following diagram shows the configuration produced by the above code. Note that the left and right dock widgets will occupy the top and bottom @@ -255,7 +255,7 @@ Once all of the main window components have been set up, the central widget is created and installed by using code similar to the following: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3 + \snippet code/doc_src_qt4-mainwindow.cpp 3 The central widget can be any subclass of QWidget. */ |
