diff options
Diffstat (limited to 'doc/src/examples')
39 files changed, 2144 insertions, 103 deletions
diff --git a/doc/src/examples/application.qdoc b/doc/src/examples/application.qdoc index 0dad46b..96e81b3 100644 --- a/doc/src/examples/application.qdoc +++ b/doc/src/examples/application.qdoc @@ -45,7 +45,7 @@ The Application example shows how to implement a standard GUI application with menus, toolbars, and a status bar. The example - itself is a simple text editor program built around QTextEdit. + itself is a simple text editor program built around QPlainTextEdit. \image application.png Screenshot of the Application example @@ -103,7 +103,7 @@ \snippet examples/mainwindows/application/mainwindow.cpp 1 \snippet examples/mainwindows/application/mainwindow.cpp 2 - In the constructor, we start by creating a QTextEdit widget as a + In the constructor, we start by creating a QPlainTextEdit widget as a child of the main window (the \c this object). Then we call QMainWindow::setCentralWidget() to tell that this is going to be the widget that occupies the central area of the main window, @@ -114,9 +114,9 @@ functions that set up the user interface. After that, we call \c readSettings() to restore the user's preferences. - We establish a signal-slot connection between the QTextEdit's + We establish a signal-slot connection between the QPlainTextEdit's document object and our \c documentWasModified() slot. Whenever - the user modifies the text in the QTextEdit, we want to update + the user modifies the text in the QPlainTextEdit, we want to update the title bar to show that the file was modified. At the end, we set the window title using the private @@ -141,7 +141,7 @@ The \c newFile() slot is invoked when the user selects \menu{File|New} from the menu. We call \c maybeSave() to save any pending changes and if the user accepts to go on, we clear the - QTextEdit and call the private function \c setCurrentFile() to + QPlainTextEdit and call the private function \c setCurrentFile() to update the window title and clear the \l{QWidget::windowModified}{windowModified} flag. @@ -187,7 +187,7 @@ \snippet examples/mainwindows/application/mainwindow.cpp 16 The \c documentWasModified() slot is invoked each time the text - in the QTextEdit changes because of user edits. We call + in the QPlainTextEdit changes because of user edits. We call QWidget::setWindowModified() to make the title bar show that the file was modified. How this is done varies on each platform. @@ -227,8 +227,8 @@ \snippet examples/mainwindows/application/mainwindow.cpp 24 The \gui{Edit|Cut} and \gui{Edit|Copy} actions must be available - only when the QTextEdit contains selected text. We disable them - by default and connect the QTextEdit::copyAvailable() signal to + only when the QPlainTextEdit contains selected text. We disable them + by default and connect the QPlainTextEdit::copyAvailable() signal to the QAction::setEnabled() slot, ensuring that the actions are disabled when the text editor has no selection. @@ -289,7 +289,7 @@ When restoring the position and size of a window, it's important to call QWidget::resize() before QWidget::move(). The reason why - is given in the \l{geometry.html}{Window Geometry} overview. + is given in the \l{Window Geometry} overview. \snippet examples/mainwindows/application/mainwindow.cpp 37 \snippet examples/mainwindows/application/mainwindow.cpp 39 diff --git a/doc/src/examples/arrowpad.qdoc b/doc/src/examples/arrowpad.qdoc index c1cde5b..95d6893 100644 --- a/doc/src/examples/arrowpad.qdoc +++ b/doc/src/examples/arrowpad.qdoc @@ -140,10 +140,10 @@ QLocale::system() can be influenced by setting the \c LANG environment variable, for example. Notice that the use of a naming convention that incorporates the locale for \c .qm message files, - (and \c .ts files), makes it easy to implement choosing the + (and TS files), makes it easy to implement choosing the translation file according to locale. - If there is no \c .qm message file for the locale chosen the original + If there is no QM message file for the locale chosen the original source text will be used and no error raised. \section1 Translating to French and Dutch @@ -194,9 +194,9 @@ \endlist We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source - files into \c .qm files. We could use \e {Qt Linguist} as we've done + files into QM files. We could use \e {Qt Linguist} as we've done before; however using the command line tool \c lrelease ensures that - \e all the \c .qm files for the application are created without us + \e all the QM files for the application are created without us having to remember to load and \gui File|Release each one individually from \e {Qt Linguist}. diff --git a/doc/src/examples/audiodevices.qdoc b/doc/src/examples/audiodevices.qdoc new file mode 100644 index 0000000..0954b7c --- /dev/null +++ b/doc/src/examples/audiodevices.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multimedia/audio/audiodevices + \title Audio Devices Example + + The Audio Devices example demonstrates the basic use of QAudioDeviceInfo class + provided with Qt. + + Qt provides the QAudioDeviceInfo class to enable audio querying within + a standard application user interface. + + This example allows you to browse audio devices available and try out different + configurations to see if they are supported. +*/ diff --git a/doc/src/examples/audioinput.qdoc b/doc/src/examples/audioinput.qdoc new file mode 100644 index 0000000..e276e6b --- /dev/null +++ b/doc/src/examples/audioinput.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multimedia/audio/audioinput + \title AudioInput Example + + The Audio Input example demonstrates the basic use of QAudioInput class + provided with Qt. + + Qt provides the QAudioInput class to enable audio functionality within + a standard application user interface. + + This example uses a fast-fourier transform on the input audio from the microphone + and displays the output. +*/ diff --git a/doc/src/examples/audiooutput.qdoc b/doc/src/examples/audiooutput.qdoc new file mode 100644 index 0000000..194a856 --- /dev/null +++ b/doc/src/examples/audiooutput.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multimedia/audio/audiooutput + \title Audio Output Example + + The Audio Output example demonstrates the basic use of the QAudioOutput class + provided with Qt. + + This example provides a tone generator to supply continuous audio playback. + The first button allows pause and resume of the playback. + The second button allows toggling between push and pull modes of operation. +*/ diff --git a/doc/src/examples/basicgraphicslayouts.qdoc b/doc/src/examples/basicgraphicslayouts.qdoc index 3b6df09..e6ca461 100644 --- a/doc/src/examples/basicgraphicslayouts.qdoc +++ b/doc/src/examples/basicgraphicslayouts.qdoc @@ -45,6 +45,7 @@ The Basic Graphics Layouts example shows how to use the layout classes in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout. + In addition to that it shows how to write your own custom layout item. \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example @@ -115,26 +116,24 @@ \section1 LayoutItem Class Definition - The \c LayoutItem class is a subclass of QGraphicsWidget. It has a - constructor, a destructor, and a reimplementation of the - {QGraphicsItem::paint()}{paint()} function. + The \c LayoutItem class is a subclass of QGraphicsLayoutItem and + QGraphicsItem. It has a constructor, a destructor, and some required + reimplementations. + Since it inherits QGraphicsLayoutItem it must reimplement + {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and + {QGraphicsLayoutItem::sizeHint()}{sizeHint()}. + In addition to that it inherits QGraphicsItem, so it must reimplement + {QGraphicsItem::boundingRect()}{boundingRect()} and + {QGraphicsItem::paint()}{paint()}. \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.h 0 - The \c LayoutItem class also has a private instance of QPixmap, \c pix. - - \note We subclass QGraphicsWidget so that \c LayoutItem objects can - be automatically plugged into a layout, as QGraphicsWidget is a - specialization of QGraphicsLayoutItem. + The \c LayoutItem class also has a private instance of QPixmap, \c m_pix. \section1 LayoutItem Class Implementation - In \c{LayoutItem}'s constructor, \c pix is instantiated and the - \c{QT_original_R.png} image is loaded into it. We set the size of - \c LayoutItem to be slightly larger than the size of the pixmap as we - require some space around it for borders that we will paint later. - Alternatively, you could scale the pixmap to prevent the item from - becoming smaller than the pixmap. + In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the + \c{block.png} image is loaded into it. \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 0 @@ -148,4 +147,32 @@ \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 2 + The reimplementation of {QGraphicsItem::boundingRect()}{boundingRect()} + will set the top left corner at (0,0), and the size of it will be + the size of the layout items + {QGraphicsLayoutItem::geometry()}{geometry()}. This is the area that + we paint within. + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 3 + + + The reimplementation of {QGraphicsLayoutItem::setGeometry()}{setGeometry()} + simply calls its baseclass implementation. However, since this will change + the boundingRect we must also call + {QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}. + Finally, we move the item according to \c geom.topLeft(). + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 4 + + + Since we don't want the size of the item to be smaller than the pixmap, we + must make sure that we return a size hint that is larger than \c m_pix. + We also add some extra space around for borders that we will paint later. + Alternatively, you could scale the pixmap to prevent the item from + becoming smaller than the pixmap. + The preferred size is the same as the minimum size hint, while we set + maximum to be a large value + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 5 + */
\ No newline at end of file diff --git a/doc/src/examples/calculatorform.qdoc b/doc/src/examples/calculatorform.qdoc index 50b7a3e..76bbcc1 100644 --- a/doc/src/examples/calculatorform.qdoc +++ b/doc/src/examples/calculatorform.qdoc @@ -45,8 +45,8 @@ The Calculator Form Example shows how to use a form created with \QD in an application by using the user interface information from - a QWidget subclass. We use \l{Using a Designer .ui File in Your Application} - {uic's auto-connection} feature to automatically connect signals + a QWidget subclass. We use \l{Using a Designer UI File in Your Application} + {uic's auto-connection} feature to automatically connect signals from widgets on the form to slots in our code. \image calculatorform-example.png Screenshot of the Calculator Form example @@ -59,7 +59,7 @@ \section1 Preparation The user interface for this example is designed completely using \QD. The - result is a .ui file describing the form, the widgets used, any signal-slot + result is a UI file describing the form, the widgets used, any signal-slot connections between them, and other standard user interface properties. To ensure that the example can use this file, we need to include a \c FORMS diff --git a/doc/src/examples/collidingmice-example.qdoc b/doc/src/examples/collidingmice-example.qdoc index f51fc38..65db544 100644 --- a/doc/src/examples/collidingmice-example.qdoc +++ b/doc/src/examples/collidingmice-example.qdoc @@ -95,11 +95,11 @@ the global qrand() function which is a thread-safe version of the standard C++ rand() function. - Then we call the \l {QGraphicsItem::rotate()}{rotate()} function + Then we call the \l {QGraphicsItem::setRotation()}{setRotation()} function inherited from QGraphicsItem. Items live in their own local coordinate system. Their coordinates are usually centered around (0, 0), and this is also the center for all transformations. By - calling the item's \l {QGraphicsItem::rotate()}{rotate()} function + calling the item's \l {QGraphicsItem::setRotation()}{setRotation()} function we alter the direction in which the mouse will start moving. When the QGraphicsScene decides to advance the scene a frame it will call diff --git a/doc/src/examples/completer.qdoc b/doc/src/examples/completer.qdoc index f4c381e..7b4b4f9 100644 --- a/doc/src/examples/completer.qdoc +++ b/doc/src/examples/completer.qdoc @@ -100,9 +100,9 @@ \section1 MainWindow Class Definition - The \c MainWindow class is a subclass of QMainWindow and implements four - private slots - \c about(), \c changeCase(), \c changeMode(), and - \c changeModel(). + The \c MainWindow class is a subclass of QMainWindow and implements five + private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(), + and \c changeMaxVisible(). \snippet examples/tools/completer/mainwindow.h 0 @@ -126,6 +126,9 @@ \snippet examples/tools/completer/mainwindow.cpp 0 + The \c maxVisibleSpinBox is created and determines the number of visible + item in the completer + The \c wrapCheckBox is then set up. This \c checkBox determines if the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property is enabled or disabled. @@ -242,10 +245,15 @@ \snippet examples/tools/completer/mainwindow.cpp 14 - The \c about() function provides a brief description about the example. + The \c changeMaxVisible() update the maximum number of visible items in + the completer. \snippet examples/tools/completer/mainwindow.cpp 15 + The \c about() function provides a brief description about the example. + + \snippet examples/tools/completer/mainwindow.cpp 16 + \section1 \c main() Function The \c main() function instantiates QApplication and \c MainWindow and diff --git a/doc/src/examples/contiguouscache.qdoc b/doc/src/examples/contiguouscache.qdoc new file mode 100644 index 0000000..c79f5c3 --- /dev/null +++ b/doc/src/examples/contiguouscache.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/contiguouscache + \title Contiguous Cache Example + + The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for + very large models. In some environments memory is limited and, even when it + isn't, users still dislike an application using excessive memory. + Using QContiguousCache to manage a list, rather than loading + the entire list into memory, allows the application to limit the amount + of memory it uses, regardless of the size of the data set it accesses + + The simplest way to use QContiguousCache is to cache as items are requested. When + a view requests an item at row N it is also likely to ask for items at rows near + to N. + + \snippet examples/tools/contiguouscache/randomlistmodel.cpp 0 + + After getting the row, the class determines if the row is in the bounds + of the contiguous cache's current range. It would have been equally valid to + simply have the following code instead. + + \code + while (row > m_rows.lastIndex()) + m_rows.append(fetchWord(m_rows.lastIndex()+1); + while (row < m_rows.firstIndex()) + m_rows.prepend(fetchWord(m_rows.firstIndex()-1); + \endcode + + However a list will often jump rows if the scroll bar is used directly, resulting in + the code above causing every row between the old and new rows to be fetched. + + Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows + the example to determine what part of the list the cache is currently caching. + These values don't represent the indexes into the cache's own memory, but rather + a virtual infinite array that the cache represents. + + By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures + that items that may be still on the screen are not lost when the requested row + has not moved far from the current cache range. QContiguousCache::insert() can + potentially remove more than one item from the cache as QContiguousCache does not + allow for gaps. If your cache needs to quickly jump back and forth between + rows with significant gaps between them consider using QCache instead. + + And thats it. A perfectly reasonable cache, using minimal memory for a very large + list. In this case the accessor for getting the words into the cache + generates random information rather than fixed information. This allows you + to see how the cache range is kept for a local number of rows when running the + example. + + \snippet examples/tools/contiguouscache/randomlistmodel.cpp 1 + + It is also worth considering pre-fetching items into the cache outside of the + application's paint routine. This can be done either with a separate thread + or using a QTimer to incrementally expand the range of the cache prior to + rows being requested out of the current cache range. +*/ diff --git a/doc/src/examples/drilldown.qdoc b/doc/src/examples/drilldown.qdoc index 18436c0..96bf512 100644 --- a/doc/src/examples/drilldown.qdoc +++ b/doc/src/examples/drilldown.qdoc @@ -389,9 +389,7 @@ the item's hover events, animating the item when the mouse cursor is hovering over the image (by default, no items accept hover events). Please see the \l{The Graphics View Framework} - documentation and the - \l{Qt Examples#Graphics View}{Graphics View examples} for more - details. + documentation and the \l{Graphics View Examples} for more details. \snippet examples/sql/drilldown/view.cpp 5 diff --git a/doc/src/examples/eventtransitions.qdoc b/doc/src/examples/eventtransitions.qdoc new file mode 100644 index 0000000..48a7f5c --- /dev/null +++ b/doc/src/examples/eventtransitions.qdoc @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/eventtransitions + \title Event Transitions Example + + The Event Transitions example shows how to use event transitions, a + feature of \l{The State Machine Framework}. + + \snippet examples/statemachine/eventtransitions/main.cpp 0 + + The \c Window class's constructors begins by creating a button. + + \snippet examples/statemachine/eventtransitions/main.cpp 1 + + Two states, \c s1 and \c s2, are created; upon entry they will assign + "Outside" and "Inside" to the button's text, respectively. + + \snippet examples/statemachine/eventtransitions/main.cpp 2 + + When the button receives an event of type QEvent::Enter and the state + machine is in state \c s1, the machine will transition to state \c s2. + + \snippet examples/statemachine/eventtransitions/main.cpp 3 + + When the button receives an event of type QEvent::Leave and the state + machine is in state \c s2, the machine will transition back to state \c + s1. + + \snippet examples/statemachine/eventtransitions/main.cpp 4 + + Next, the state \c s3 is created. \c s3 will be entered when the button + receives an event of type QEvent::MouseButtonPress and the state machine + is in state \c s2. When the button receives an event of type + QEvent::MouseButtonRelease and the state machine is in state \c s3, the + machine will transition back to state \c s2. + + \snippet examples/statemachine/eventtransitions/main.cpp 5 + + Finally, the states are added to the machine as top-level states, the + initial state is set to be \c s1 ("Outside"), and the machine is started. + + \snippet examples/statemachine/eventtransitions/main.cpp 6 + + The main() function constructs a Window object and shows it. + +*/ diff --git a/doc/src/examples/factorial.qdoc b/doc/src/examples/factorial.qdoc new file mode 100644 index 0000000..7933f5d --- /dev/null +++ b/doc/src/examples/factorial.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/factorial + \title Factorial States Example + + The Factorial States example shows how to use \l{The State Machine + Framework} to calculate the factorial of an integer. + + The statechart for calculating the factorial looks as follows: + + \img factorial-example.png + \omit + \caption This is a caption + \endomit + + In other words, the state machine calculates the factorial of 6 and prints + the result. + + \snippet examples/statemachine/factorial/main.cpp 0 + + The Factorial class is used to hold the data of the computation, \c x and + \c fac. It also provides a signal that's emitted whenever the value of \c + x changes. + + \snippet examples/statemachine/factorial/main.cpp 1 + + The FactorialLoopTransition class implements the guard (\c x > 1) and + calculations (\c fac = \c x * \c fac; \c x = \c x - 1) of the factorial + loop. + + \snippet examples/statemachine/factorial/main.cpp 2 + + The FactorialDoneTransition class implements the guard (\c x <= 1) that + terminates the factorial computation. It also prints the final result to + standard output. + + \snippet examples/statemachine/factorial/main.cpp 3 + + The application's main() function first creates the application object, a + Factorial object and a state machine. + + \snippet examples/statemachine/factorial/main.cpp 4 + + The \c compute state is created, and the initial values of \c x and \c fac + are defined. A FactorialLoopTransition object is created and added to the + state. + + \snippet examples/statemachine/factorial/main.cpp 5 + + A final state, \c done, is created, and a FactorialDoneTransition object + is created with \c done as its target state. The transition is then added + to the \c compute state. + + \snippet examples/statemachine/factorial/main.cpp 6 + + The machine's initial state is set to be the \c compute state. We connect + the QStateMachine::finished() signal to the QCoreApplication::quit() slot, + so the application will quit when the state machine's work is + done. Finally, the state machine is started, and the application's event + loop is entered. + + */ diff --git a/doc/src/examples/helloscript.qdoc b/doc/src/examples/helloscript.qdoc index 236464c..3d02d99 100644 --- a/doc/src/examples/helloscript.qdoc +++ b/doc/src/examples/helloscript.qdoc @@ -121,7 +121,7 @@ window). Don't forget the exclamation mark! Click the \gui Done checkbox and choose \gui File|Save from the - menu bar. The \c .ts file will no longer contain + menu bar. The TS file will no longer contain \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 @@ -129,11 +129,11 @@ \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 - To see the application running in Latin, we have to generate a \c .qm - file from the \c .ts file. Generating a \c .qm file can be achieved - either from within \e {Qt Linguist} (for a single \c .ts file), or - by using the command line program \c lrelease which will produce one \c - .qm file for each of the \c .ts files listed in the project file. + To see the application running in Latin, we have to generate a QM + file from the TS file. Generating a QM file can be achieved + either from within \e {Qt Linguist} (for a single TS file), or + by using the command line program \c lrelease which will produce one + QM file for each of the TS files listed in the project file. Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing \gui File|Release from \e {Qt Linguist}'s menu bar and pressing \gui Save in the file save dialog that pops up. Now run the \c helloscript diff --git a/doc/src/examples/hellotr.qdoc b/doc/src/examples/hellotr.qdoc index c5fee8c..978f61f 100644 --- a/doc/src/examples/hellotr.qdoc +++ b/doc/src/examples/hellotr.qdoc @@ -108,12 +108,12 @@ Note that the file extension is \c .ts, not \c .qm. The \c .ts translation source format is designed for use during the application's development. Programmers or release managers run - the \c lupdate program to generate and update \c .ts files with + the \c lupdate program to generate and update TS files with the source text that is extracted from the source code. - Translators read and update the \c .ts files using \e {Qt + Translators read and update the TS files using \e {Qt Linguist} adding and editing their translations. - The \c .ts format is human-readable XML that can be emailed directly + The TS format is human-readable XML that can be emailed directly and is easy to put under version control. If you edit this file manually, be aware that the default encoding for XML is UTF-8, not Latin1 (ISO 8859-1). One way to type in a Latin1 character such as @@ -121,8 +121,8 @@ "\ø". This will work for any Unicode 4.0 character. Once the translations are complete the \c lrelease program is used to - convert the \c .ts files into the \c .qm Qt message file format. The - \c .qm format is a compact binary format designed to deliver very + convert the TS files into the QM Qt message file format. The + QM format is a compact binary format designed to deliver very fast lookup performance. Both \c lupdate and \c lrelease read all the project's source and header files (as specified in the HEADERS and SOURCES lines of the project file) and extract the strings that @@ -131,7 +131,7 @@ \c lupdate is used to create and update the message files (\c hellotr_la.ts in this case) to keep them in sync with the source code. It is safe to run \c lupdate at any time, as \c lupdate does not remove any - information. For example, you can put it in the makefile, so the \c .ts + information. For example, you can put it in the makefile, so the TS files are updated whenever the source changes. Try running \c lupdate right now, like this: @@ -151,7 +151,7 @@ We will use \e {Qt Linguist} to provide the translation, although you can use any XML or plain text editor to enter a translation into a - \c .ts file. + TS file. To start \e {Qt Linguist}, type @@ -163,7 +163,7 @@ window). Don't forget the exclamation mark! Click the \gui Done checkbox and choose \gui File|Save from the - menu bar. The \c .ts file will no longer contain + menu bar. The TS file will no longer contain \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 @@ -173,11 +173,11 @@ \section1 Running the Application in Latin - To see the application running in Latin, we have to generate a \c .qm - file from the \c .ts file. Generating a \c .qm file can be achieved - either from within \e {Qt Linguist} (for a single \c .ts file), or - by using the command line program \c lrelease which will produce one \c - .qm file for each of the \c .ts files listed in the project file. + To see the application running in Latin, we have to generate a QM + file from the TS file. Generating a QM file can be achieved + either from within \e {Qt Linguist} (for a single TS file), or + by using the command line program \c lrelease which will produce one + QM file for each of the TS files listed in the project file. Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing \gui File|Release from \e {Qt Linguist}'s menu bar and pressing \gui Save in the file save dialog that pops up. Now run the \c hellotr diff --git a/doc/src/examples/htmlinfo.qdoc b/doc/src/examples/htmlinfo.qdoc new file mode 100644 index 0000000..68e8320 --- /dev/null +++ b/doc/src/examples/htmlinfo.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/htmlinfo + \title XML HTML Info Example + + The XML HTML Info example provides a simple command line utility that + scans the current directory for HTML files and prints statistics about + them to standard out. + + \note Standard out is redirected on some platforms. On Symbian using Open + C \c stdout is by default directed to the console window, but this window + may not always be visible. To redirect to a file instead, locate the \c + c:\\system\\data\\config.ini file (on either the emulator or the device) + and change \c STDOUT to point to \c MEDIA4. This will redirect the console + to \c c:\\system\\data\\out.txt. + + The files are parsed using a QXmlStreamReader object. If the file does + not contain a well-formed XML document, a description of the error is + printed to the standard error console. + + \section1 Basic Operation + + The main function of the example uses QDir to access files in the current + directory that match either "*.htm" or "*.html". For each file found, + the \c parseHtmlFile() function is called. + + Reading XML is handled by an instance of the QXmlStreamReader class, which + operates on the input file object: + + \snippet examples/xml/htmlinfo/main.cpp 0 + + The work of parsing and the XML and extracting statistics is done in a + while loop, and is driven by input from the reader: + + \snippet examples/xml/htmlinfo/main.cpp 1 + + If more input is available, the next token from the input file is read + and parsed. The program then looks for the specific element types, + "title", "a", and "p", and stores information about them. + + When there is no more input, the loop terminates. If an error occurred, + information is written to the standard out file via a stream, and the + example exits: + + \snippet examples/xml/htmlinfo/main.cpp 2 + + If no error occurred, the example prints some statistics from the data + gathered in the loop, and then exits. +*/ diff --git a/doc/src/examples/inputpanel.qdoc b/doc/src/examples/inputpanel.qdoc new file mode 100644 index 0000000..06c19ba --- /dev/null +++ b/doc/src/examples/inputpanel.qdoc @@ -0,0 +1,238 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/inputpanel + \title Input Panel Example + + The Input Panel example shows how to create an input panel that + can be used to input text into widgets using only the pointer and + no keyboard. + + \image inputpanel-example.png + + The input fields in the main window have no function other than + to accept input. The main focus is on how the extra input panel + can be used to input text without the need for a real keyboard or + keypad. + + \section1 Main Form Class Definition + + Because the main window has no other function than to accept + input, it has no class definition. Instead, its whole layout is + made in Qt Designer. This emphasizes the point that no widget + specific code is needed to use input panels with Qt. + + \section1 MyInputPanelContext Class Definition + + \snippet examples/tools/inputpanel/myinputpanelcontext.h 0 + + The \c MyInputPanelContext class inherits QInputContext, which is + Qt's base class for handling input methods. + \c MyInputPanelContext is responsible for managing the state of + the input panel and sending input method events to the receiving + widgets. + + The \c inputPanel member is a pointer to the input panel widget + itself; in other words, the window that will display the buttons + used for input. + + The \c identifierName(), \c language(), \c isComposing() and + \c reset() functions are there mainly to fill in the pure virtual + functions in the base class, QInputContext, but they can be + useful in other scenarios. The important functions and slots are + the following: + + \list + \o \c filterEvent() is where we receive events telling us to open + or close the input panel. + \o \c sendCharacter() is a slot which is called when we want to + send a character to the focused widget. + \o \c updatePosition() is used to position the input panel + relative to the focused widget, and will be used when opening + the input panel. + \endlist + + \section1 MyInputPanelContext Class Implementation + + In the constructor we connect to the \c characterGenerated() + signal of the input panel, in order to receive key presses. We'll + see how it works in detail later on. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 0 + + In the \c filterEvent() function, we must look for the two event + types: \c RequestSoftwareInputPanel and \c CloseSoftwareInputPanel. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 1 + + The first type will be sent whenever + an input capable widget wants to ask for an input panel. Qt's + input widgets do this automatically. If we receive that type of + event, we call \c updatePosition() \mdash we'll see later on what it + does \mdash then show the actual input panel widget. If we receive + the \c CloseSoftwareInputPanel event, we do the opposite, and + hide the input panel. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 2 + + We implement the \c sendCharacter() function so that it sends the + supplied character to the focused widget. All QInputContext based + classes are always supposed to send events to the widget returned + by QInputContext::focusWidget(). Note the QPointer guards to make + sure that the widget does not get destroyed in between events. + + Also note that we chose to use key press events in this example. + For more complex use cases with composed text it might be more + appropriate to send QInputMethodEvent events. + + The \c updatePosition() function is implemented to position the + actual input panel window directly below the focused widget. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 3 + + It performs the positioning by obtaining the coordinates of the + focused widget and translating them to global coordinates. + + \section1 MyInputPanel Class Definition + + The \c MyInputPanel class inherits QWidget and is used to display + the input panel widget and its buttons. + + \snippet examples/tools/inputpanel/myinputpanel.h 0 + + If we look at the member variables first, we see that there is + \c form, which is made with Qt Designer, that contains the layout + of buttons to click. Note that all the buttons in the layout have + been declared with the \c NoFocus focus policy so that we can + maintain focus on the window receiving input instead of the + window containing buttons. + + The \c lastFocusedWidget is a helper variable, which also aids in + maintaining focus. + + \c signalMapper is an instance of the QSignalMapper class and is + there to help us tell which button was clicked. Since they are + all very similar this is a better solution than creating a separate + slot for each one. + + The functions that we implement in \c MyInputPanel are the + following: + + \list + \o \c event() is used to intercept and manipulate focus events, + so we can maintain focus in the main window. + \o \c saveFocusWidget() is a slot which will be called whenever + focus changes, and allows us to store the newly focused widget + in \c lastFocusedWidget, so that its focus can be restored + if it loses it to the input panel. + \o \c buttonClicked() is a slot which will be called by the + \c signalMapper whenever it receives a \c clicked() signal + from any of the buttons. + \endlist + + \section1 MyInputPanel Class Implementation + + If we look at the constructor first, we have a lot of signals to + connect to! + + We connect the QApplication::focusChanged() signal + to the \c saveFocusWidget() signal in order to get focus updates. + Then comes the interesting part with the signal mapper: the + series of \c setMapping() calls sets the mapper up so that each + signal from one of the buttons will result in a + QSignalMapper::mapped() signal, with the given widget as a + parameter. This allows us to do general processing of clicks. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 0 + + The next series of connections then connect each button's + \c clicked() signal to the signal mapper. Finally, we create + a connection from the \c mapped() signal to the + \c buttonClicked() slot, where we will handle it. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 3 + + In the \c buttonClicked() slot, we extract the value of the + "buttonValue" property. This is a custom property which was + created in Qt Designer and set to the character that we wish the + button to produce. Then we emit the \c characterGenerated() + signal, which \c MyInputPanelContext is connected to. This will + in turn cause it to send the input to the focused widget. + + In the \c saveFocusWidget() slot, we test whether the newly + focused widget is a child of the input panel or not, using the + QWidget::isAncestorOf() call. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 2 + + If it isn't, it means that the widget is outside the input panel, + and we store a pointer to that widget for later. + + In the \c event() function we handle QEvent::WindowActivate + event, which occurs if the focus switches to the input panel. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 1 + + Since we want avoid focus on the input panel, we immediately call + QWidget::activateWindow() on the widget that last had focus, so + that input into that widget can continue. We ignore any other events + that we receive. + + \section1 Setting the Input Context + + The main function for the example is very similar to those for other + examples. The only real difference is that it creates a + \c MyInputPanelContext and sets it as the application-wide input + context. + + \snippet examples/tools/inputpanel/main.cpp main + + With the input context in place, we set up and show the user interface + made in Qt Designer before running the event loop. + + \section1 Further Reading + + This example shows a specific kind of input context that uses interaction + with a widget to provide input for another. Qt's input context system can + also be used to create other kinds of input methods. We recommend starting + with the QInputContext documentation if you want to explore further. +*/ diff --git a/doc/src/examples/moveblocks.qdoc b/doc/src/examples/moveblocks.qdoc new file mode 100644 index 0000000..97fbe77 --- /dev/null +++ b/doc/src/examples/moveblocks.qdoc @@ -0,0 +1,228 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/moveblocks + \title Move Blocks Example + + The Move Blocks example shows how to animate items in a + QGraphicsScene using a QStateMachine with a custom transition. + + \image moveblocks-example.png + + The example animates the blue blocks that you can see in the image + above. The animation moves the blocks between four preset positions. + + The example consists of the following classes: + + \list + \o \c StateSwitcher inherits QState and can add + \c {StateSwitchTransition}s to other states. + When entered, it will randomly transition to one of these + states. + \o \c StateSwitchTransition is a custom transition that + triggers on \c{StateSwitchEvent}s. + \o \c StateSwitchEvent is a QEvent that trigger \c{StateSwitchTransition}s. + \o \c QGraphicsRectWidget is a QGraphicsWidget that simply + paints its background in a solid \l{Qt::}{blue} color. + \endlist + + The blocks are instances of \c QGraphicsRectWidget and are + animated in a QGraphicsScene. We do this by building a state + graph, which we insert animations into. The graph is then executed + in a QStateMachine. All this is done in \c main(). + Let's look at the \c main() function first. + + \section1 The \c main() Function + + After QApplication has been initialized, we set up the + QGraphicsScene with its \c{QGraphicsRectWidget}s. + + \snippet examples/animation/moveblocks/main.cpp 1 + + After adding the scene to a QGraphicsView, it is time to build the + state graph. Let's first look at a statechart of what we are + trying to build. + + \image move-blocks-chart.png + + Note that the \c group has seven sub states, but we have only + included three of them in the diagram. The code that builds this + graph will be examined line-by-line, and will show how the graph + works. First off, we construct the \c group state: + + \snippet examples/animation/moveblocks/main.cpp 2 + + The timer is used to add a delay between each time the blocks are + moved. The timer is started when \c group is entered. As we will + see later, \c group has a transition back to the \c StateSwitcher + when the timer times out. \c group is the initial state in the + machine, so an animation will be scheduled when the example is + started. + + \snippet examples/animation/moveblocks/main.cpp 3 + \dots + \snippet examples/animation/moveblocks/main.cpp 4 + + \c createGeometryState() returns a QState that will set the + geometry of our items upon entry. It also assigns \c group as the + parent of this state. + + A QPropertyAnimation inserted into a transition will use the + values assigned to a QState (with QState::assignProperty()), i.e., + the animation will interpolate between the current values of the + properties and the values in the target state. We add animated + transitions to the state graph later. + + \snippet examples/animation/moveblocks/main.cpp 5 + + We move the items in parallel. Each item is added to \c + animationGroup, which is the animation that is inserted into the + transitions. + + \snippet examples/animation/moveblocks/main.cpp 6 + + The sequential animation group, \c subGroup, helps us insert a + delay between the animation of each item. + + \snippet examples/animation/moveblocks/main.cpp 7 + \dots + \snippet examples/animation/moveblocks/main.cpp 8 + + A StateSwitchTransition is added to the state switcher + in \c StateSwitcher::addState(). We also add the animation in this + function. Since QPropertyAnimation uses the values from the + states, we can insert the same QPropertyAnimation instance in all + \c {StateSwitchTransition}s. + + As mentioned previously, we add a transition to the state switcher + that triggers when the timer times out. + + \snippet examples/animation/moveblocks/main.cpp 9 + + Finally, we can create the state machine, add our initial state, + and start execution of the state graph. + + \section2 The \c createGemetryState() Function + + In \c createGeometryState(), we set up the geometry for each + graphics item. + + \snippet examples/animation/moveblocks/main.cpp 13 + + As mentioned before, QAbstractTransition will set up an animation + added with \l{QAbstractTransition::}{addAnimation()} using + property values set with \l{QState::}{assignProperty()}. + + \section1 The StateSwitcher Class + + \c StateSwitcher has state switch transitions to each \l{QState}s + we created with \c createGemetryState(). Its job is to transition + to one of these states at random when it is entered. + + All functions in \c StateSwitcher are inlined. We'll step through + its definition. + + \snippet examples/animation/moveblocks/main.cpp 10 + + \c StateSwitcher is a state designed for a particular purpose and + will always be a top-level state. We use \c m_stateCount to keep + track of how many states we are managing, and \c m_lastIndex to + remember which state was the last state to which we transitioned. + + \snippet examples/animation/moveblocks/main.cpp 11 + + We select the next state we are going to transition to, and post a + \c StateSwitchEvent, which we know will trigger the \c + StateSwitchTransition to the selected state. + + \snippet examples/animation/moveblocks/main.cpp 12 + + This is where the magic happens. We assign a number to each state + added. This number is given to both a StateSwitchTransition and to + StateSwitchEvents. As we have seen, state switch events will + trigger a transition with the same number. + + \section1 The StateSwitchTransition Class + + \c StateSwitchTransition inherits QAbstractTransition and triggers + on \c{StateSwitchEvent}s. It contains only inline functions, so + let's take a look at its \l{QAbstractTransition::}{eventTest()} + function, which is the only function that we define.. + + \snippet examples/animation/moveblocks/main.cpp 14 + + \c eventTest is called by QStateMachine when it checks whether a + transition should be triggered--a return value of true means that + it will. We simply check if our assigned number is equal to the + event's number (in which case we fire away). + + \section1 The StateSwitchEvent Class + + \c StateSwitchEvent inherits QEvent, and holds a number that has + been assigned to a state and state switch transition by + \c StateSwitcher. We have already seen how it is used to trigger + \c{StateSwitchTransition}s in \c StateSwitcher. + + \snippet examples/animation/moveblocks/main.cpp 15 + + We only have inlined functions in this class, so a look at its + definition will do. + + \section1 The QGraphicsRectWidget Class + + QGraphicsRectWidget inherits QGraphicsWidget and simply paints its + \l{QWidget::}{rect()} blue. We inline \l{QWidget::}{paintEvent()}, + which is the only function we define. Here is the + QGraphicsRectWidget class definition: + + \snippet examples/animation/moveblocks/main.cpp 16 + + \section1 Moving On + + The technique shown in this example works equally well for all + \l{QPropertyAnimation}s. As long as the value to be animated is a + Qt property, you can insert an animation of it into a state graph. + + QState::addAnimation() takes a QAbstractAnimation, so any type + of animation can be inserted into the graph. +*/ + diff --git a/doc/src/examples/multipleinheritance.qdoc b/doc/src/examples/multipleinheritance.qdoc index 9d0ea84..7840033 100644 --- a/doc/src/examples/multipleinheritance.qdoc +++ b/doc/src/examples/multipleinheritance.qdoc @@ -103,6 +103,6 @@ There are various approaches to include forms into applications. The Multiple Inheritance approach is just one of them. See - \l{Using a Designer .ui File in Your Application} for more information on + \l{Using a Designer UI File in Your Application} for more information on the other approaches available. */ diff --git a/doc/src/examples/overpainting.qdoc b/doc/src/examples/overpainting.qdoc index 3deddd6..2abcd00 100644 --- a/doc/src/examples/overpainting.qdoc +++ b/doc/src/examples/overpainting.qdoc @@ -159,9 +159,10 @@ \snippet examples/opengl/overpainting/glwidget.cpp 7 - Once the list containing the object has been executed, the matrix stack - needs to be restored to its original state at the start of this function - before we can begin overpainting: + Once the list containing the object has been executed, the GL + states we changed and the matrix stack needs to be restored to its + original state at the start of this function before we can begin + overpainting: \snippet examples/opengl/overpainting/glwidget.cpp 8 diff --git a/doc/src/examples/pingpong.qdoc b/doc/src/examples/pingpong.qdoc new file mode 100644 index 0000000..d3a3f18 --- /dev/null +++ b/doc/src/examples/pingpong.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/pingpong + \title Ping Pong States Example + + The Ping Pong States example shows how to use parallel states together + with custom events and transitions in \l{The State Machine Framework}. + + This example implements a statechart where two states communicate by + posting events to the state machine. The state chart looks as follows: + + \img pingpong-example.png + \omit + \caption This is a caption + \endomit + + The \c pinger and \c ponger states are parallel states, i.e. they are + entered simultaneously and will take transitions independently of + eachother. + + The \c pinger state will post the first \c ping event upon entry; the \c + ponger state will respond by posting a \c pong event; this will cause the + \c pinger state to post a new \c ping event; and so on. + + \snippet examples/statemachine/pingpong/main.cpp 0 + + Two custom events are defined, \c PingEvent and \c PongEvent. + + \snippet examples/statemachine/pingpong/main.cpp 1 + + The \c Pinger class defines a state that posts a \c PingEvent to the state + machine when the state is entered. + + \snippet examples/statemachine/pingpong/main.cpp 2 + + The \c PingTransition class defines a transition that is triggered by + events of type \c PingEvent, and that posts a \c PongEvent (with a delay + of 500 milliseconds) to the state machine when the transition is + triggered. + + \snippet examples/statemachine/pingpong/main.cpp 3 + + The \c PongTransition class defines a transition that is triggered by + events of type \c PongEvent, and that posts a \c PingEvent (with a delay + of 500 milliseconds) to the state machine when the transition is + triggered. + + \snippet examples/statemachine/pingpong/main.cpp 4 + + The main() function begins by creating a state machine and a parallel + state group. + + \snippet examples/statemachine/pingpong/main.cpp 5 + + Next, the \c pinger and \c ponger states are created, with the parallel + state group as their parent state. Note that the transitions are \e + targetless. When such a transition is triggered, the source state won't be + exited and re-entered; only the transition's onTransition() function will + be called, and the state machine's configuration will remain the same, + which is precisely what we want in this case. + + \snippet examples/statemachine/pingpong/main.cpp 6 + + Finally, the group is added to the state machine, the machine is started, + and the application event loop is entered. + + */ diff --git a/doc/src/examples/qtscriptcalculator.qdoc b/doc/src/examples/qtscriptcalculator.qdoc index ffe4686..2320e5e 100644 --- a/doc/src/examples/qtscriptcalculator.qdoc +++ b/doc/src/examples/qtscriptcalculator.qdoc @@ -42,7 +42,6 @@ /*! \example script/calculator \title QtScript Calculator Example - \ingroup scripting In this simple QtScript example, we show how to implement the functionality of a calculator widget. @@ -90,10 +89,8 @@ \snippet examples/script/calculator/calculator.js 1 - The digitClicked() function uses the special local variable - __qt_sender__ to access the object that triggered the signal; - this gives us a simple way to retrieve the value of the digit - that was clicked. + The digitClicked() function is called when a digit button is + clicked, with the input digit as argument. \snippet examples/script/calculator/calculator.js 2 diff --git a/doc/src/examples/qtscripttetrix.qdoc b/doc/src/examples/qtscripttetrix.qdoc index 8f754cb..b39eee7 100644 --- a/doc/src/examples/qtscripttetrix.qdoc +++ b/doc/src/examples/qtscripttetrix.qdoc @@ -57,7 +57,7 @@ \section1 Setting up the GUI - The graphical user interface is defined in a \c{.ui} file, creating + The graphical user interface is defined in a UI file, created using Qt Designer, and is set up in the example's C++ \c{main.cpp} file. \snippet examples/script/qstetrix/main.cpp 0 diff --git a/doc/src/examples/qxmlstreambookmarks.qdoc b/doc/src/examples/qxmlstreambookmarks.qdoc index 3ced592..616f8fe 100644 --- a/doc/src/examples/qxmlstreambookmarks.qdoc +++ b/doc/src/examples/qxmlstreambookmarks.qdoc @@ -51,10 +51,10 @@ \section1 XbelWriter Class Definition - The \c XbelWriter class is a subclass of QXmlStreamReader, which provides - an XML parser with a streaming API. \c XbelWriter also contains a private - instance of QTreeWidget in order to display the bookmarks according to - hierarchies. + The \c XbelWriter class contains a private instance of QXmlStreamWriter, + which provides an XML writer with a streaming API. \c XbelWriter also + has a reference to the QTreeWidget instance where the bookmark hierarchy + is stored. \snippet examples/xml/streambookmarks/xbelwriter.h 0 @@ -75,7 +75,7 @@ \snippet examples/xml/streambookmarks/xbelwriter.cpp 1 - The \c writeItem() function accepts a QTreeWidget object and writes it + The \c writeItem() function accepts a QTreeWidgetItem object and writes it to the stream, depending on its \c tagName, which can either be a "folder", "bookmark", or "separator". @@ -83,9 +83,10 @@ \section1 XbelReader Class Definition - The \c XbelReader class is a subclass of QXmlStreamReader, the pendent - class for QXmlStreamWriter. \c XbelReader contains a private instance - of QTreeWidget to group bookmarks according to their hierarchies. + The \c XbelReader contains a private instance of QXmlStreamReader, the + companion class to QXmlStreamWriter. \c XbelReader also contains a + reference to the QTreeWidget that is used to group the bookmarks according + to their hierarchy. \snippet examples/xml/streambookmarks/xbelreader.h 0 @@ -102,23 +103,27 @@ \snippet examples/xml/streambookmarks/xbelreader.cpp 0 The \c read() function accepts a QIODevice and sets it using - \l{QXmlStreamReader::setDevice()}{setDevice()}. The actual process - of reading only takes place if the file is a valid XBEL 1.0 file. - Note that the XML input needs to be well-formed to be accepted by - QXmlStreamReader. Otherwise, the \l{QXmlStreamReader::raiseError()} - {raiseError()} function is used to display an error message. + \l{QXmlStreamReader::}{setDevice()}. The actual process of reading only + takes place if the file is a valid XBEL 1.0 file. Note that the XML input + needs to be well-formed to be accepted by QXmlStreamReader. Otherwise, the + \l{QXmlStreamReader::}{raiseError()} function is used to display an error + message. Since the XBEL reader is only concerned with reading XML elements, + it makes extensive use of the \l{QXmlStreamReader::}{readNextStartElement()} + convenience function. \snippet examples/xml/streambookmarks/xbelreader.cpp 1 - The \c readUnknownElement() function reads an unknown element. The - Q_ASSERT() macro is used to provide a pre-condition for the function. + The \c errorString() function is used if an error occurred, in order to + obtain a description of the error complete with line and column number + information. \snippet examples/xml/streambookmarks/xbelreader.cpp 2 The \c readXBEL() function reads the name of a startElement and calls the appropriate function to read it, depending on whether if its a "folder", "bookmark" or "separator". Otherwise, it calls - \c readUnknownElement(). + \l{QXmlStreamReader::}{skipCurrentElement()}. The Q_ASSERT() macro is used + to provide a pre-condition for the function. \snippet examples/xml/streambookmarks/xbelreader.cpp 3 @@ -127,8 +132,8 @@ \snippet examples/xml/streambookmarks/xbelreader.cpp 4 The \c readSeparator() function creates a separator and sets its flags. - The text is set to 30 "0xB7", the HEX equivalent for period, and then - read using \c readElementText(). + The text is set to 30 "0xB7", the HEX equivalent for period. The element + is then skipped using \l{QXmlStreamReader::}{skipCurrentElement()}. \snippet examples/xml/streambookmarks/xbelreader.cpp 5 diff --git a/doc/src/examples/rogue.qdoc b/doc/src/examples/rogue.qdoc new file mode 100644 index 0000000..dfd7804 --- /dev/null +++ b/doc/src/examples/rogue.qdoc @@ -0,0 +1,222 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/rogue + \title Rogue Example + + The Rogue example shows how to use the Qt state machine for event + handling. + + \image rogue-example.png + + This example implements a simple text based game. Do you see the + \c{@} in the screenshot? That's you, the rogue. The \c{#} + characters are walls, and the dots represent floor. In a real + game, other ASCII characters would represent all kinds of objects + and creatures. For instance, ancient dragons (\c{D}'s) or food + rations (\c{%}'s). But let's not get carried away. In this game, + the rogue is simply running around in an empty room. + + The rogue is moved with the keypad (2, 4, 8, 6). That aside, we + have implemented a \c quit command that triggers if the player + types \c {q}. The player is then asked if he/she really wants to + quit. + + Most games have commands that need more than one key press and + that may require a different sequence of keys based on questions + asked the user. In this game, only the \c quit command falls under + this category, but for the sake of argument, let's imagine a + fully-fledged game with a rich set of commands. If we were to + implement these by catching key events in + \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of + class member variables to track the sequence of keys already typed + (or find some other way of deducing the current state of a + command). This can easily lead to spaghetti, which is--as we all + well know, I'm sure--unpleasant. With a state machine, on the + other hand, separate states can wait for a single key press, and + that makes our lives a lot simpler. + + The example consists of two classes: + + \list + \o \c Window draws the text display of the game and sets + up the state machine. The window also has a status bar + above the area in which the rouge moves. + \o \c MovementTransition is a transition that carries out + a single move of the rogue. + \endlist + + Before we embark on a code walkthrough, it is necessary to take a + closer look at the design of the machine. Here is a state chart + that shows what we want to achieve: + + \image rogue-statechart.png + + The input state waits for a key press to start a new command. + When receiving a key it recognizes, it transitions to one of the + two commands of the game; though, as we will see, movement is + handled by the transition itself. The quit state waits for the + player to answer yes or no (by typing \c y or \c n) when asked + whether he/she really wants to quit the game. + + The chart demonstrates how we use one state to wait for a single + key press. The press received may trigger one of the transitions + connected to the state. + + \section1 Window Class Definition + + The \c Window class is a widget that draws the text display of the + game. It also sets up the state machine, i.e., creates and + connects the states in the machine. It is the key events from this + widget that are used by the machine. + + \snippet examples/statemachine/rogue/window.h 0 + + \c Direction specifies the direction in which the rogue is to + move. We use this in \c movePlayer(), which moves the rogue and + repaints the window. The game has a status line above the area in + which the rogue moves. The \c status property contains the text of + this line. We use a property because the QState class allows + setting any Qt \l{Qt's Property System}{property} when entered. + More on this later. + + \snippet examples/statemachine/rogue/window.h 1 + + The \c map is an array with the characters that are currently + displayed. We set up the array in \c setupMap(), and update it + when the rogue is moved. \c pX and \c pY is the current position + of the rogue. \c WIDTH and \c HEIGHT are macros specifying the + dimensions of the map. + + The \c paintEvent() function is left out of this walkthrough. We + also do not discuss other code that does not concern the state + machine (the \c setupMap(), \c status(), \c setStatus(), \c + movePlayer(), and \c sizeHint() functions). If you wish to take a + look at the code, click on the link for the \c window.cpp file at + the top of this page. + + \section1 Window Class Implementation + + Here is the constructor of \c Window: + + \snippet examples/statemachine/rogue/window.cpp 0 + \dots + \snippet examples/statemachine/rogue/window.cpp 1 + + The player starts off at position (5, 5). We then set up the map + and statemachine. Let's proceed with the \c buildMachine() + function: + + \snippet examples/statemachine/rogue/window.cpp 2 + + We enter \c inputState when the machine is started and from the \c + quitState if the user wants to continue playing. We then set the + status to a helpful reminder of how to play the game. + + First, the \c Movement transition is added to the input state. + This will enable the rogue to be moved with the keypad. Notice + that we don't set a target state for the movement transition. This + will cause the transition to be triggered (and the + \l{QAbstractTransition::}{onTransition()} function to be invoked), + but the machine will not leave the \c inputState. If we had set \c + inputState as the target state, we would first have left and then + entered the \c inputState again. + + \snippet examples/statemachine/rogue/window.cpp 3 + + When we enter \c quitState, we update the status bar of the + window. + + \c QKeyEventTransition is a utility class that removes the hassle + of implementing transitions for \l{QKeyEvent}s. We simply need to + specify the key on which the transition should trigger and the + target state of the transition. + + \snippet examples/statemachine/rogue/window.cpp 4 + + The transition from \c inputState allows triggering the quit state + when the player types \c {q}. + + \snippet examples/statemachine/rogue/window.cpp 5 + + The machine is set up, so it's time to start it. + + \section1 The MovementTransition Class + + \c MovementTransition is triggered when the player request the + rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in + the \c inputState. + + \snippet examples/statemachine/rogue/movementtransition.h 0 + + In the constructor, we tell QEventTransition to only send + \l{QEvent::}{KeyPress} events to the + \l{QAbstractTransition::}{eventTest()} function: + + \snippet examples/statemachine/rogue/movementtransition.h 1 + + The KeyPress events come wrapped in \l{QWrappedEvent}s. \c event + must be confirmed to be a wrapped event because Qt uses other + events internally. After that, it is simply a matter of checking + which key has been pressed. + + Let's move on to the \c onTransition() function: + + \snippet examples/statemachine/rogue/movementtransition.h 2 + + When \c onTransition() is invoked, we know that we have a + \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, i.e., the event + is already unwrapped. + + \section1 The Roguelike Tradition + + You might have been wondering why the game features a rogue. Well, + these kinds of text based dungeon exploration games date back to a + game called, yes, "Rogue". Although outflanked by the technology + of modern 3D computer games, roguelikes have a solid community of + hard-core, devoted followers. + + Playing these games can be surprisingly addictive (despite the + lack of graphics). Angband, the perhaps most well-known rougelike, + is found here: \l{http://rephial.org/}. +*/ + diff --git a/doc/src/examples/schema.qdoc b/doc/src/examples/schema.qdoc new file mode 100644 index 0000000..4cd80c2 --- /dev/null +++ b/doc/src/examples/schema.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xmlpatterns/schema + \title XML Schema Validation Example + + This example shows how to use QtXmlPatterns to validate XML with + a W3C XML Schema. + + \tableofcontents + + \section1 Introduction + + The example application shows different XML schema definitions and + for every definition two XML instance documents, one that is valid + according to the schema and one that is not. + The user can select the valid or invalid instance document, change + it and validate it again. + + \section2 The User Interface + + The UI for this example was created using \l{Qt Designer Manual} {Qt + Designer}: + + \image schema-example.png + + The UI consists of three parts, at the top the XML schema \l{QComboBox} {selection} + and the schema \l{QTextBrowser} {viewer}, below the XML instance \l{QComboBox} {selection} + and the instance \l{QTextEdit} {editor} and at the bottom the validation status \l{QLabel} {label} + next to the validation \l{QPushButton} {button}. + + \section2 Validating XML Instance Documents + + You can select one of the three predefined XML schemas and for each schema + an valid or invalid instance document. A click on the 'Validate' button will + validate the content of the XML instance editor against the schema from the + XML schema viewer. As you can modify the content of the instance editor, different + instances can be tested and validation error messages analysed. + + \section1 Code Walk-Through + + The example's main() function creates the standard instance of + QApplication. Then it creates an instance of the mainwindow class, shows it, + and starts the Qt event loop: + + \snippet examples/xmlpatterns/schema/main.cpp 0 + + \section2 The UI Class: MainWindow + + The example's UI is a conventional Qt GUI application inheriting + QMainWindow and the class generated by \l{Qt Designer Manual} {Qt + Designer}: + + \snippet examples/xmlpatterns/schema/mainwindow.h 0 + + The constructor fills the schema and instance \l{QComboBox} selections with the predefined + schemas and instances and connects their \l{QComboBox::currentIndexChanged()} {currentIndexChanged()} + signals to the window's \c{schemaSelected()} resp. \c{instanceSelected()} slot. + Furthermore the signal-slot connections for the validation \l{QPushButton} {button} + and the instance \l{QTextEdit} {editor} are set up. + + The call to \c{schemaSelected(0)} and \c{instanceSelected(0)} will trigger the validation + of the initial Contact Schema example. + + \snippet examples/xmlpatterns/schema/mainwindow.cpp 0 + + In the \c{schemaSelected()} slot the content of the instance \l{QComboBox} {selection} + is adapted to the selected schema and the corresponding schema is loaded from the + \l{The Qt Resource System} {resource file} and displayed in the schema \l{QTextBrowser} {viewer}. + At the end of the method a revalidation is triggered. + + \snippet examples/xmlpatterns/schema/mainwindow.cpp 1 + + In the \c{instanceSelected()} slot the selected instance is loaded from the + \l{The Qt Resource System} {resource file} and loaded into the instance \l{QTextEdit} {editor} + an the revalidation is triggered again. + + \snippet examples/xmlpatterns/schema/mainwindow.cpp 2 + + The \c{validate()} slot does the actual work in this example. + At first it stores the content of the schema \l{QTextBrowser} {viewer} and the + \l{QTextEdit} {editor} into temporary \l{QByteArray} {variables}. + Then it instanciates a \c{MessageHandler} object which inherits from + \l{QAbstractMessageHandler} {QAbstractMessageHandler} and is a convenience + class to store error messages from the XmlPatterns system. + + \snippet examples/xmlpatterns/schema/mainwindow.cpp 4 + + After the \l{QXmlSchema} {QXmlSchema} is instanciated and the message handler set + on it, the \l{QXmlSchema::load()} {load()} method is called with the schema data as argument. + If the schema is invalid or a parsing error has occured, \l{QXmlSchema::isValid()} {isValid()} + returns \c{false} and the error is flagged in \c{errorOccurred}. + If the loading was successful, a \l{QXmlSchemaValidator} {QXmlSchemaValidator} is + instanciated and the schema passed in the constructor. + A call to \l{QXmlSchemaValidator::validate()} {validate()} will validate the passed + XML instance data against the XML schema. The return value of that method signals + whether the validation was successful. + Depending on the success the status \l{QLabel} {label} is set to 'validation successful' + or the error message stored in the \c{MessageHandler} + + The rest of the code does only some fancy coloring and eyecandy. + + \snippet examples/xmlpatterns/schema/mainwindow.cpp 3 +*/ diff --git a/doc/src/examples/scribble.qdoc b/doc/src/examples/scribble.qdoc index 0283e4d..b57c8eb 100644 --- a/doc/src/examples/scribble.qdoc +++ b/doc/src/examples/scribble.qdoc @@ -354,7 +354,7 @@ To retrieve a new pen width in the \c penWidth() slot, we use QInputDialog. The QInputDialog class provides a simple convenience dialog to get a single value from the user. We use - the static QInputDialog::getInteger() function, which combines a + the static QInputDialog::getInt() function, which combines a QLabel and a QSpinBox. The QSpinBox is initialized with the scribble area's pen width, allows a range from 1 to 50, a step of 1 (meaning that the up and down arrow increment or decrement the diff --git a/doc/src/examples/simpletextviewer.qdoc b/doc/src/examples/simpletextviewer.qdoc index ac85186..94e1318 100644 --- a/doc/src/examples/simpletextviewer.qdoc +++ b/doc/src/examples/simpletextviewer.qdoc @@ -198,12 +198,7 @@ <file>openfile.html</file> <file>wildcardmatching.html</file> <file>images/browse.png</file> - <file>images/fadedfilemenu.png</file> - <file>images/filedialog.png</file> - <file>images/handbook.png</file> - <file>images/mainwindow.png</file> - <file>images/open.png</file> - <file>images/wildcard.png</file> + <file>images/*.png</file> </files> </filterSection> </QtHelpProject> diff --git a/doc/src/examples/stickman.qdoc b/doc/src/examples/stickman.qdoc new file mode 100644 index 0000000..496996e --- /dev/null +++ b/doc/src/examples/stickman.qdoc @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/stickman + \title Stickman Example + + The Stickman example shows how to animate transitions in a state machine to implement key frame + animations. + + \image stickman-example.png + + In this example, we will write a small application which animates the joints in a skeleton and + projects a stickman figure on top. The stickman can be either "alive" or "dead", and when in the + "alive" state, he can be performing different actions defined by key frame animations. + + Animations are implemented as composite states. Each child state of the animation state + represents a frame in the animation by setting the position of each joint in the stickman's + skeleton to the positions defined for the particular frame. The frames are then bound together + with animated transitions that trigger on the source state's polished() signal. Thus, the + machine will enter the state representing the next frame in the animation immediately after it + has finished animating into the previous frame. + + \image stickman-example1.png + + The states for an animation is constructed by reading a custom animation file format and + creating states that assign values to the the "position" properties of each of the nodes in the + skeleton graph. + + \snippet examples/animation/stickman/lifecycle.cpp 1 + + The states are then bound together with signal transitions that listen to the polished() signal. + + \snippet examples/animation/stickman/lifecycle.cpp 2 + + The last frame state is given a transition to the first one, so that the animation will loop + until it is interrupted when a transition out from the animation state is taken. To get smooth + animations between the different key frames, we set a default animation on the state machine. + This is a parallel animation group which contains animations for all the "position" properties + and will be selected by default when taking any transition that leads into a state that assigns + values to these properties. + + \snippet examples/animation/stickman/lifecycle.cpp 3 + + Several such animation states are constructed, and are placed together as children of a top + level "alive" state which represents the stickman life cycle. Transitions go from the parent + state to the child state to ensure that each of the child states inherit them. + + \image stickman-example2.png + + This saves us the effort of connect every state to every state with identical transitions. The + state machine makes sure that transitions between the key frame animations are also smooth by + applying the default animation when interrupting one and starting another. + + Finally, there is a transition out from the "alive" state and into the "dead" state. This is + a custom transition type called LightningSrikesTransition which samples every second and + triggers at random (one out of fifty times on average.) + + \snippet examples/animation/stickman/lifecycle.cpp 4 + + When it triggers, the machine will first enter a "lightningBlink" state which uses a timer to + pause for a brief period of time while the background color of the scene is white. This gives us + a flash effect when the lightning strikes. + + \snippet examples/animation/stickman/lifecycle.cpp 5 + + We start and stop a QTimer object when entering and exiting the state. Then we transition into + the "dead" state when the timer times out. + + \snippet examples/animation/stickman/lifecycle.cpp 0 + + When the machine is in the "dead" state, it will be unresponsive. This is because the "dead" + state has no transitions leading out. + + \image stickman-example3.png + +*/ diff --git a/doc/src/examples/svggenerator.qdoc b/doc/src/examples/svggenerator.qdoc index cd2a0a8..3fb2f0d 100644 --- a/doc/src/examples/svggenerator.qdoc +++ b/doc/src/examples/svggenerator.qdoc @@ -55,8 +55,8 @@ The example consists of two classes: \c Window and \c DisplayWidget. The \c Window class contains the application logic and constructs the user - interface from a Qt Designer \c{.ui} file as described in the - \l{Using a Designer .ui File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. + interface from a Qt Designer UI file as described in the + \l{Using a Designer UI File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. It also contains the code to write an SVG file. The \c DisplayWidget class performs all the work of painting a picture on diff --git a/doc/src/examples/tablet.qdoc b/doc/src/examples/tablet.qdoc index bf10171..dd3086b 100644 --- a/doc/src/examples/tablet.qdoc +++ b/doc/src/examples/tablet.qdoc @@ -275,7 +275,10 @@ In this function we draw on the image based on the movement of the device. If the device used on the tablet is a stylus we want to draw a - line between the positions of the stylus recorded in \c polyLine. + line between the positions of the stylus recorded in \c polyLine. We + also assume that this is a reasonable handling of any unknown device, + but update the statusbar with a warning so that the user can see that + for his tablet he might have to implement special handling. If it is an airbrush we want to draw a circle of points with a point density based on the tangential pressure, which is the position of the finger wheel on the airbrush. We use the Qt::BrushStyle to diff --git a/doc/src/examples/textfinder.qdoc b/doc/src/examples/textfinder.qdoc index 0f672dc..0b5db79 100644 --- a/doc/src/examples/textfinder.qdoc +++ b/doc/src/examples/textfinder.qdoc @@ -45,7 +45,7 @@ The Text Finder example demonstrates how to dynamically process forms using the QtUiTools module. Dynamic form processing enables a form to - be processed at run-time only by changing the .ui file for the project. + be processed at run-time only by changing the UI file for the project. The program allows the user to look up a particular word within the contents of a text file. This text file is included in the project's resource and is loaded into the display at startup. @@ -95,7 +95,7 @@ \snippet examples/uitools/textfinder/textfinder.h 0 The slot \c{on_find_Button_clicked()} is a slot named according to the - \l{Using a Designer .ui File in Your Application#Automatic Connections} + \l{Using a Designer UI File in Your Application#Automatic Connections} {Automatic Connection} naming convention required by \c uic. diff --git a/doc/src/examples/trafficinfo.qdoc b/doc/src/examples/trafficinfo.qdoc index 3d06584..ca90b977 100644 --- a/doc/src/examples/trafficinfo.qdoc +++ b/doc/src/examples/trafficinfo.qdoc @@ -159,5 +159,5 @@ The rest of the code in this example is just for representing the time and station information to the user, and uses techniques described in the - \l{Qt Examples#Widgets}{Widgets examples}. + \l{Widgets Examples}. */ diff --git a/doc/src/examples/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc new file mode 100644 index 0000000..e0f16b5 --- /dev/null +++ b/doc/src/examples/trafficlight.qdoc @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/trafficlight + \title Traffic Light Example + + The Traffic Light example shows how to use \l{The State Machine Framework} + to implement the control flow of a traffic light. + + \image trafficlight-example.png + + In this example we write a TrafficLightWidget class. The traffic light has + three lights: Red, yellow and green. The traffic light transitions from + one light to another (red to yellow to green to yellow to red again) at + certain intervals. + + \snippet examples/statemachine/trafficlight/main.cpp 0 + + The LightWidget class represents a single light of the traffic light. It + provides an \c on property and two slots, turnOn() and turnOff(), to turn + the light on and off, respectively. The widget paints itself in the color + that's passed to the constructor. + + \snippet examples/statemachine/trafficlight/main.cpp 1 + + The TrafficLightWidget class represents the visual part of the traffic + light; it's a widget that contains three lights arranged vertically, and + provides accessor functions for these. + + \snippet examples/statemachine/trafficlight/main.cpp 2 + + The createLightState() function creates a state that turns a light on when + the state is entered, and off when the state is exited. The state uses a + timer, and as we shall see the timeout is used to transition from one + LightState to another. Here is the statechart for the light state: + + \img trafficlight-example1.png + \omit + \caption This is a caption + \endomit + + \snippet examples/statemachine/trafficlight/main.cpp 3 + + The TrafficLight class combines the TrafficLightWidget with a state + machine. The state graph has four states: red-to-yellow, yellow-to-green, + green-to-yellow and yellow-to-red. The initial state is red-to-yellow; + when the state's timer times out, the state machine transitions to + yellow-to-green. The same process repeats through the other states. + This is what the statechart looks like: + + \img trafficlight-example2.png + \omit + \caption This is a caption + \endomit + + \snippet examples/statemachine/trafficlight/main.cpp 4 + + The main() function constructs a TrafficLight and shows it. + +*/ diff --git a/doc/src/examples/transformations.qdoc b/doc/src/examples/transformations.qdoc index 01d4ebe..f5e8865 100644 --- a/doc/src/examples/transformations.qdoc +++ b/doc/src/examples/transformations.qdoc @@ -85,10 +85,10 @@ All the tranformation operations operate on QPainter's tranformation matrix that you can retrieve using the - QPainter::matrix() function. A matrix transforms a point in the + QPainter::worldTransform() function. A matrix transforms a point in the plane to another point. For more information about the transformation matrix, see the \l {The Coordinate System} and - QMatrix documentation. + QTransform documentation. \snippet examples/painting/transformations/renderarea.h 0 @@ -375,7 +375,7 @@ All the tranformation operations operate on QPainter's tranformation matrix. For more information about the transformation matrix, see the \l {The Coordinate System} and - QMatrix documentation. + QTransform documentation. The Qt reference documentation provides several painting demos. Among these is the \l {demos/affine}{Affine diff --git a/doc/src/examples/twowaybutton.qdoc b/doc/src/examples/twowaybutton.qdoc new file mode 100644 index 0000000..8e6aa44 --- /dev/null +++ b/doc/src/examples/twowaybutton.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/twowaybutton + \title Two-way Button Example + + The Two-way button example shows how to use \l{The State Machine + Framework} to implement a simple state machine that toggles the current + state when a button is clicked. + + \snippet examples/statemachine/twowaybutton/main.cpp 0 + + The application's main() function begins by constructing the application + object, a button and a state machine. + + \snippet examples/statemachine/twowaybutton/main.cpp 1 + + The state machine has two states; \c on and \c off. When either state is + entered, the text of the button will be set accordingly. + + \snippet examples/statemachine/twowaybutton/main.cpp 2 + + When the state machine is in the \c off state and the button is clicked, + it will transition to the \c on state; when the state machine is in the \c + on state and the button is clicked, it will transition to the \c off + state. + + \snippet examples/statemachine/twowaybutton/main.cpp 3 + + The states are added to the state machine; they become top-level (sibling) + states. + + \snippet examples/statemachine/twowaybutton/main.cpp 4 + + The initial state is \c off; this is the state the state machine will + immediately transition to once the state machine is started. + + \snippet examples/statemachine/twowaybutton/main.cpp 5 + + Finally, the button is resized and made visible, and the application event + loop is entered. + +*/ diff --git a/doc/src/examples/videographicsitem.qdoc b/doc/src/examples/videographicsitem.qdoc new file mode 100644 index 0000000..861b587 --- /dev/null +++ b/doc/src/examples/videographicsitem.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example video/videographicsitem + \title Video Graphics Item Example + + The Video Graphics Item example shows how to implement a QGraphicsItem that displays video on a + graphics scene using QtMultimedia's QAbstractVideoSurface. + + \image video-videographicsitem.png + + \sa {Video Widget Example} +*/ diff --git a/doc/src/examples/videowidget.qdoc b/doc/src/examples/videowidget.qdoc new file mode 100644 index 0000000..27d5711 --- /dev/null +++ b/doc/src/examples/videowidget.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example video/videowidget + \title Video Widget Example + + The Video Widget example shows how to implement a video widget using + QtMultimedia's QAbstractVideoSurface + + \image video-videowidget.png + + \section1 VideoWidgetSurface Class Definition + + \snippet examples/video/videowidget/videowidgetsurface.h 0 + + The VideoWidgetSurface class inherits QAbstractVideoSurface and paints + video frames on a QWidget. This is a separate class to VideoWidget as both + QAbstractVideoSurface and QWidget inherit QObject. + + In addition to the functions from QAbstractVideoSurface, VideoWidgetSurface + has functions for determining the video display rectangle, and painting + the video. + + \section1 VideoWidgetSurface Class Implementation + + \snippet examples/video/videowidget/videowidgetsurface.cpp 0 + + From the supportedPixelFormats() function we return a list of pixel formats + the surface can paint. The order of the list hints at which formats are + preferred by the surface. Assuming a 32-bit RGB backbuffer, we'd expect + that a 32-bit RGB type with no alpha to be fastest to paint so + QVideoFrame::Image_RGB32 is first in the list. + + Since we don't support rendering using any special frame handles we don't + return any pixel formats if handleType is not + QAbstractVideoBuffer::NoHandle. + + \snippet examples/video/videowidget/videowidgetsurface.cpp 1 + + In isFormatSupported() we test if the frame type of a surface format maps + to a valid QImage format, that the frame size is not empty, and the handle + type is QAbstractVideoBuffer::NoHandle. Note that the + QAbstractVideoSurface implementation of isFormatSupported() will verify + that the list of supported pixel formats returned by + \c supportedPixelFormats(format.handleType()) contains the pixel format and + that the size is not empty so a reimplementation wasn't strictly necessary + in this case. + + \snippet examples/video/videowidget/videowidgetsurface.cpp 2 + + To start our surface we'll extract the image format and size from the + selected video format and save it for use in the paint() function. If the + image format, or size are invalid then we'll set an error and return false. + Otherwise we'll save the format and confirm the surface has been started, + by calling QAbstractVideoSurface::start(). Finally since the video size may + have changed we'll trigger an update of the widget, and video geometry. + + \snippet examples/video/videowidget/videowidgetsurface.cpp 5 + + The updateVideoRect() function calculates the region within the widget the + video occupies. The \l {QVideoSurfaceFormat::sizeHint()}{size hint} of the + video format gives a suggested size for the video calculated from the + \l {QVideoSurfaceFormat::viewport()}{viewport} and + \l {QVideoSurfaceFormat::pixelAspectRatio()}{pixel aspect ratio}. If the + suggested size fits within the widget then we create a new rect of that + size in the center of the widget. Otherwise we shrink the size maintaining + the aspect ratio so that it does fit. + + \snippet examples/video/videowidget/videowidgetsurface.cpp 4 + + We can't paint from outside a paint event, so when a new frame is received + in present() we save a reference to it and force an immediate repaint of + the video region. We retain the saved reference to the frame after the + repaint so that the widget can be repainted between frame changes if + necessary. + + If the format of the frame doesn't match the surface format we can't paint + it or very likely any future frames. So we set an + \l {QAbstractVideoSurface::UnsupportedFormatError}{UnsupportedFormatError} + on our surface and stop it immediately. + + \snippet examples/video/videowidget/videowidgetsurface.cpp 6 + + The paint() function is called by the video widget to paint the current + video frame. Before we draw the frame first we'll check the format for + the scan line direction and if the scan lines are arranged from bottom to + top we'll flip the painter so the frame isn't drawn upside down. Then + using the image format information saved in the start() function we'll + construct a new QImage from the current video frame, and draw it to the + the widget. + + \snippet examples/video/videowidget/videowidgetsurface.cpp 3 + + When the surface is stopped we need to release the current frame and + invalidate the video region. Then we confirm the surface has been + stopped by calling QAbstractVideoSurface::stop() which sets the started + state to false and finally we update so the video widget so paints over + the last frame. + + \section1 VideoWidget Class Definition + + The VideoWidget class uses the VideoWidgetSurface class to implement a + video widget. + + \snippet examples/video/videowidget/videowidget.h 0 + + The VideoWidget QWidget implementation is minimal with just the sizeHint(), + paintEvent(), and resizeEvent() functions in addition to the constructor, + destructor and an instance of VideoWidgetSurface. + + \section1 VideoWidget Class Implementation + + \snippet examples/video/videowidget/videowidget.cpp 0 + + In the VideoWidget constructor we set some flags to speed up re-paints a + little. Setting the Qt::WA_NoSystemBackground flag and disabling automatic + background fills will stop Qt from a painting a background that'll be + completely obscured by the video. The Qt::WA_PaintOnScreen flag will + allow us to paint to the screen instead of the back buffer where supported. + + Next we set the background color to black, so that any borders around the + video are filled in black rather the default background color. + + Finally we construct an instance of the VideoWidgetSurface class. + + \snippet examples/video/videowidget/videowidget.cpp 1 + + In the destructor we simply delete the VideoWidgetSurface instance. + + \snippet examples/video/videowidget/videowidget.cpp 2 + + We get the size hint for the widget from the video format of the surface + which is calculated from viewport and pixel aspect ratio of the video + format. + + \snippet examples/video/videowidget/videowidget.cpp 3 + + When the video widget receives a paint event we first check if the surface + is started, if not then we simply fill the widget with the background + color. If it is then we draw a border around the video region clipped + by the paint region, before calling paint on the video surface to draw the + current frame. + + \snippet examples/video/videowidget/videowidget.cpp 4 + + The resizeEvent() function is reimplemented to trigger an update of the + video region when the widget is resized. +*/ diff --git a/doc/src/examples/worldtimeclockbuilder.qdoc b/doc/src/examples/worldtimeclockbuilder.qdoc index c2a502f..f5734c4 100644 --- a/doc/src/examples/worldtimeclockbuilder.qdoc +++ b/doc/src/examples/worldtimeclockbuilder.qdoc @@ -66,7 +66,7 @@ generate a dependency on the \c libQtUiTools library containing the QtUiTools classes. - Note that we do not inform \c qmake about any .ui files, and so none will + Note that we do not inform \c qmake about any UI files, and so none will be processed and built into the application. The resource file contains an entry for the particular form that we wish to use: |