diff options
Diffstat (limited to 'doc')
48 files changed, 1003 insertions, 388 deletions
diff --git a/doc/doc.pri b/doc/doc.pri index 6b77f88..a4c77fe 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -4,7 +4,7 @@ win32 { QT_WINCONFIG = release/ - CONFIG(debug, debug|release) { + !CONFIG(release, debug|release) { QT_WINCONFIG = debug/ } } @@ -24,7 +24,7 @@ $$unixstyle { QDOC = cd $$QT_SOURCE_TREE/tools/qdoc3/test && QT_BUILD_TREE=$$QT_BUILD_TREE QT_SOURCE_TREE=$$QT_SOURCE_TREE $$QT_BUILD_TREE/tools/qdoc3/$${QT_WINCONFIG}qdoc3 $$DOCS_GENERATION_DEFINES } else { QDOC = cd $$QT_SOURCE_TREE/tools/qdoc3/test && set QT_BUILD_TREE=$$QT_BUILD_TREE&& set QT_SOURCE_TREE=$$QT_SOURCE_TREE&& $$QT_BUILD_TREE/tools/qdoc3/$${QT_WINCONFIG}qdoc3.exe $$DOCS_GENERATION_DEFINES - QDOC = $$replace(QDOC, "/", "\\\\") + QDOC = $$replace(QDOC, "/", "\\") } macx { ADP_DOCS_QDOCCONF_FILE = qt-build-docs-with-xcode.qdocconf diff --git a/doc/src/activeqt.qdoc b/doc/src/activeqt.qdoc index ea13e59..473f815 100644 --- a/doc/src/activeqt.qdoc +++ b/doc/src/activeqt.qdoc @@ -73,7 +73,7 @@ To build the static libraries, change into the \c activeqt directory (usually \c QTDIR/src/activeqt), and run \c qmake and your make tool in both the \c container and the \c control subdirectory. - The libraries \c qaxcontainer.lib and \c qaxserver.lib will be linked + The libraries \c qaxcontainer.lib and \c qaxserver.lib will be linked into \c QTDIR/lib. If you are using a shared configuration of Qt enter the \c plugin @@ -81,8 +81,8 @@ plugin that integrates the QAxContainer module into \l{Qt Designer}. - The ActiveQt modules are part of the \l{Qt Full Framework Edition}. They - are \e not part of the \l{Open Source Versions of Qt}. + The ActiveQt modules are part of the \l{Qt Full Framework Edition} and + the \l{Open Source Versions of Qt}. \sa {QAxContainer Module}, {QAxServer Module} */ diff --git a/doc/src/datastreamformat.qdoc b/doc/src/datastreamformat.qdoc index 3c651fb..15ac062 100644 --- a/doc/src/datastreamformat.qdoc +++ b/doc/src/datastreamformat.qdoc @@ -69,6 +69,10 @@ the application happens to be running on. \table + \row \o bool + \o \list + \o boolean + \endlist \row \o qint8 \o \list \o signed byte @@ -297,6 +301,10 @@ \o \list \o Milliseconds since midnight (quint32) \endlist + \row \o QUrl + \o \list + \o Holds an URL (QString) + \endlist \row \o QVariant \o \list \o The type of the data (quint32) diff --git a/doc/src/deployment.qdoc b/doc/src/deployment.qdoc index d9f7c1a..bcfa93d 100644 --- a/doc/src/deployment.qdoc +++ b/doc/src/deployment.qdoc @@ -911,7 +911,7 @@ Then qApp->libraryPaths() would return something like this: "C:/customPath/plugins " - "C:/Qt/4.5.0/plugins" + "C:/Qt/%VERSION%/plugins" "E:/myApplication/directory/" The executable will look for the plugins in these directories and diff --git a/doc/src/designer-manual.qdoc b/doc/src/designer-manual.qdoc index e10a5be..03b74e6 100644 --- a/doc/src/designer-manual.qdoc +++ b/doc/src/designer-manual.qdoc @@ -344,10 +344,14 @@ of a QLineEdit or the width and height of item view widgets. This is where the widget size constraints -- \l{QWidget::minimumSize()}{minimumSize} and \l{QWidget::maximumSize()}{maximumSize} constraints come into play. These - are properties you can set in the property editor. Alternatively, to use - the current size as a size constraint value, choose one of the - \gui{Size Constraint} options from the widget's context menu. The layout - will then ensure that those constraints are met. + are properties you can set in the property editor. For example, to override + the default \l{QWidget::}{sizeHint()}, simply set + \l{QWidget::minimumSize()}{minimumSize} and \l{QWidget::maximumSize()} + {maximumSize} to the same value. Alternatively, to use the current size as + a size constraint value, choose one of the \gui{Size Constraint} options + from the widget's context menu. The layout will then ensure that those + constraints are met. To control the size of your widgets via code, you can + reimplement \l{QWidget::}{sizeHint()} in your code. The screenshot below shows the breakdown of a basic user interface designed using a grid. The coordinates on the screenshot show the position of each diff --git a/doc/src/examples-overview.qdoc b/doc/src/examples-overview.qdoc index 549574d..92ccd4e 100644 --- a/doc/src/examples-overview.qdoc +++ b/doc/src/examples-overview.qdoc @@ -319,6 +319,14 @@ from displaying Web pages within a Qt user interface to an implementation of a basic function Web browser. + \section1 \l{Qt Examples#State Machine}{State Machine} + + Qt provides a powerful hierchical finite state machine through the Qt State + Machine classes. + + These examples demonstrate the fundamental aspects of implementing + Statecharts with Qt. + \section1 \l{Qt Examples#Qt for Embedded Linux}{Qt for Embedded Linux} \l{Qt Examples#Qt for Embedded Linux}{\inlineimage qt-embedded-examples.png diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc index b750aa0..0153252 100644 --- a/doc/src/examples.qdoc +++ b/doc/src/examples.qdoc @@ -209,6 +209,7 @@ \o \l{network/loopback}{Loopback} \o \l{network/threadedfortuneserver}{Threaded Fortune Server}\raisedaster \o \l{network/torrent}{Torrent} + \o \l{network/googlesuggest}{Google Suggest} \endlist \section1 OpenGL @@ -310,7 +311,10 @@ \section1 State Machine \list + \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster + \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster + \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster \endlist \section1 Threads @@ -354,6 +358,8 @@ \list \o \l{webkit/previewer}{Previewer}\raisedaster \o \l{webkit/formextractor}{Form Extractor} + \o \l{webkit/googlechat}{Google Chat} + \o \l{webkit/fancybrowser}{Fancy Browser} \endlist \section1 Widgets diff --git a/doc/src/examples/eventtransitions.qdoc b/doc/src/examples/eventtransitions.qdoc new file mode 100644 index 0000000..3b956bb --- /dev/null +++ b/doc/src/examples/eventtransitions.qdoc @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** 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 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/snippets/webkit/simple/main.cpp b/doc/src/examples/fancybrowser.qdoc index a6a4fc2..9001c20 100644 --- a/doc/src/snippets/webkit/simple/main.cpp +++ b/doc/src/examples/fancybrowser.qdoc @@ -39,18 +39,13 @@ ** ****************************************************************************/ -#include <QApplication> -#include <QUrl> -#include <QWebView> +/*! + \example webkit/fancybrowser + \title Fancy Browser Example -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - QWidget *parent = 0; -//! [Using QWebView] - QWebView *view = new QWebView(parent); - view->load(QUrl("http://qtsoftware.com/")); - view->show(); -//! [Using QWebView] - return app.exec(); -} + The Fancy Browser example shows how to use jQuery with QtWebKit to + make a web browser with some special effects and content manipulation. + + \image fancybrowser-example.png + +*/ diff --git a/doc/src/examples/flowlayout.qdoc b/doc/src/examples/flowlayout.qdoc index 557ba39..3e7ec22 100644 --- a/doc/src/examples/flowlayout.qdoc +++ b/doc/src/examples/flowlayout.qdoc @@ -43,8 +43,117 @@ \example layouts/flowlayout \title Flow Layout Example - The Flow Layout example demonstrates a custom layout that arranges child widgets from - left to right and top to bottom in a top-level widget. + The Flow Layout example demonstrates a custom layout that arranges child + widgets from left to right and top to bottom in a top-level widget. + + \image flowlayout-example.png Screenshot of the Flow Layout example + + The items are first laid out horizontally and then vertically when each line + in the layout runs out of space. + + The Flowlayout class mainly uses QLayout and QWidgetItem, while the + Window uses QWidget and QLabel. We will only document the definition + and implementation of \c FlowLayout below. + + \section1 FlowLayout Class Definition + + The \c FlowLayout class inherits QLayout. It is a custom layout class + that arranges its child widgets horizontally and vertically. + + \snippet examples/layouts/flowlayout/flowlayout.h 0 + + We reimplement functions inherited from QLayout. These functions add items to + the layout and handle their orientation and geometry. + + We also declare two private methods, \c doLayout() and \c smartSpacing(). + \c doLayout() lays out the layout items, while the \c + smartSpacing() function calculates the spacing between them. + + \section1 FlowLayout Class Implementation + + We start off by looking at the constructor: + + \snippet examples/layouts/flowlayout/flowlayout.cpp 1 + + In the constructor we call \c setContentsMargins() to set the left, top, + right and bottom margin. By default, QLayout uses values provided by + the current style (see QStyle::PixelMetric). + + \snippet examples/layouts/flowlayout/flowlayout.cpp 2 + + In this example we reimplement \c addItem(), which is a pure virtual + function. When using \c addItem() the ownership of the layout items is + transferred to the layout, and it is therefore the layout's + responsibility to delete them. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 3 + + \c addItem() is implemented to add items to the layout. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 4 + + We implement \c horizontalSpacing() and \c verticalSpacing() to get + hold of the spacing between the widgets inside the layout. If the value + is less than or equal to 0, this value will be used. If not, + \c smartSpacing() will be called to calculate the spacing. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 5 + + We then implement \c count() to return the number of items in the + layout. To navigate the list of items we use \c itemAt() and + takeAt() to remove and return items from the list. If an item is + removed, the remaining items will be renumbered. All three + functions are pure virtual functions from QLayout. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 6 + + \c expandingDirections() returns the \l{Qt::Orientation}s in which the + layout can make use of more space than its \c sizeHint(). + + \snippet examples/layouts/flowlayout/flowlayout.cpp 7 + + To adjust to widgets of which height is dependent on width, we implement \c + heightForWidth(). The function \c hasHeightForWidth() is used to test for this + dependency, and \c heightForWidth() passes the width on to \c doLayout() which + in turn uses the width as an argument for the layout rect, i.e., the bounds in + which the items are laid out. This rect does not include the layout margin(). + + \snippet examples/layouts/flowlayout/flowlayout.cpp 8 + + \c setGeometry() is normally used to do the actual layout, i.e., calculate + the geometry of the layout's items. In this example, it calls \c doLayout() + and passes the layout rect. + + \c sizeHint() returns the preferred size of the layout and \c minimumSize() + returns the minimum size of the layout. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 9 + + \c doLayout() handles the layout if \c horizontalSpacing() or \c + verticalSpacing() don't return the default value. It uses + \c getContentsMargins() to calculate the area available to the + layout items. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 10 + + It then sets the proper amount of spacing for each widget in the + layout, based on the current style. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 11 + + The position of each item in the layout is then calculated by + adding the items width and the line height to the initial x and y + coordinates. This in turn lets us find out whether the next item + will fit on the current line or if it must be moved down to the next. + We also find the height of the current line based on the widgets height. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 12 + + \c smartSpacing() is designed to get the default spacing for either + the top-level layouts or the sublayouts. The default spacing for + top-level layouts, when the parent is a QWidget, will be determined + by querying the style. The default spacing for sublayouts, when + the parent is a QLayout, will be determined by querying the spacing + of the parent layout. - \image flowlayout-example.png */ diff --git a/doc/src/examples/googlechat.qdoc b/doc/src/examples/googlechat.qdoc new file mode 100644 index 0000000..f2d61cf --- /dev/null +++ b/doc/src/examples/googlechat.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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 webkit/googlechat + \title Google Chat Example + + The Google Chat example shows how to use implement a simple Google Chat + client with QtWebKit. + + \image googlechat-example.png + +*/ diff --git a/doc/src/examples/googlesuggest.qdoc b/doc/src/examples/googlesuggest.qdoc new file mode 100644 index 0000000..a9b09f9 --- /dev/null +++ b/doc/src/examples/googlesuggest.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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 network/googlesuggest + \title Google Suggest Example + + The Google Suggest example shows how to use the network access manager + to get the list of suggested search terms from Google. + + \image googlesuggest-example.png + +*/ diff --git a/doc/src/examples/pingpong.qdoc b/doc/src/examples/pingpong.qdoc new file mode 100644 index 0000000..040e429 --- /dev/null +++ b/doc/src/examples/pingpong.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** 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 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/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc index 16ee8ad..ae62127 100644 --- a/doc/src/examples/trafficlight.qdoc +++ b/doc/src/examples/trafficlight.qdoc @@ -1,11 +1,41 @@ /**************************************************************************** ** -** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** Contact: Qt Software Information (qt-info@nokia.com) ** -** This file is part of the $MODULE$ of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** -** $TROLLTECH_DUAL_LICENSE$ +** $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$ ** ****************************************************************************/ @@ -26,30 +56,41 @@ \snippet examples/statemachine/trafficlight/main.cpp 0 The LightWidget class represents a single light of the traffic light. It - provides a setOn() function to turn the light on or off. It paints itself - in the color that's passed to the constructor. + 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 2 + \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, and provides accessor - functions for these. + light; it's a widget that contains three lights arranged vertically, and + provides accessor functions for these. - \snippet examples/statemachine/trafficlight/main.cpp 1 + \snippet examples/statemachine/trafficlight/main.cpp 2 - The LightState class represents a state that turns a light on when the - state is entered, and off when the state is exited. The class is a timer, - and as we shall see the timeout is used to transition from one LightState - to another. + 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 control flow - based on the LightState class. 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. + 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 diff --git a/doc/src/examples/twowaybutton.qdoc b/doc/src/examples/twowaybutton.qdoc new file mode 100644 index 0000000..87de2e8 --- /dev/null +++ b/doc/src/examples/twowaybutton.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** 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 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/images/fancybrowser-example.png b/doc/src/images/fancybrowser-example.png Binary files differnew file mode 100644 index 0000000..717ac9d --- /dev/null +++ b/doc/src/images/fancybrowser-example.png diff --git a/doc/src/images/flowlayout-example.png b/doc/src/images/flowlayout-example.png Binary files differindex 27660d6..61abe1f 100644 --- a/doc/src/images/flowlayout-example.png +++ b/doc/src/images/flowlayout-example.png diff --git a/doc/src/images/googlechat-example.png b/doc/src/images/googlechat-example.png Binary files differnew file mode 100644 index 0000000..0338445 --- /dev/null +++ b/doc/src/images/googlechat-example.png diff --git a/doc/src/images/googlesuggest-example.png b/doc/src/images/googlesuggest-example.png Binary files differnew file mode 100644 index 0000000..4ef072a --- /dev/null +++ b/doc/src/images/googlesuggest-example.png diff --git a/doc/src/images/pingpong-example.png b/doc/src/images/pingpong-example.png Binary files differnew file mode 100644 index 0000000..af707e4 --- /dev/null +++ b/doc/src/images/pingpong-example.png diff --git a/doc/src/images/statemachine-button-history.png b/doc/src/images/statemachine-button-history.png Binary files differindex cd66478..7f51cae 100644 --- a/doc/src/images/statemachine-button-history.png +++ b/doc/src/images/statemachine-button-history.png diff --git a/doc/src/images/statemachine-button-nested.png b/doc/src/images/statemachine-button-nested.png Binary files differindex 60360d1..762ac14 100644 --- a/doc/src/images/statemachine-button-nested.png +++ b/doc/src/images/statemachine-button-nested.png diff --git a/doc/src/images/statemachine-button.png b/doc/src/images/statemachine-button.png Binary files differindex 75d9e53..10102bd 100644 --- a/doc/src/images/statemachine-button.png +++ b/doc/src/images/statemachine-button.png diff --git a/doc/src/images/statemachine-customevents.png b/doc/src/images/statemachine-customevents.png Binary files differnew file mode 100644 index 0000000..62a4222 --- /dev/null +++ b/doc/src/images/statemachine-customevents.png diff --git a/doc/src/images/statemachine-finished.png b/doc/src/images/statemachine-finished.png Binary files differindex 802621e..0ac081d 100644 --- a/doc/src/images/statemachine-finished.png +++ b/doc/src/images/statemachine-finished.png diff --git a/doc/src/images/statemachine-nonparallel.png b/doc/src/images/statemachine-nonparallel.png Binary files differindex 1fe60d8..f9850a7 100644 --- a/doc/src/images/statemachine-nonparallel.png +++ b/doc/src/images/statemachine-nonparallel.png diff --git a/doc/src/images/statemachine-parallel.png b/doc/src/images/statemachine-parallel.png Binary files differindex 1868792..a65c297 100644 --- a/doc/src/images/statemachine-parallel.png +++ b/doc/src/images/statemachine-parallel.png diff --git a/doc/src/images/trafficlight-example1.png b/doc/src/images/trafficlight-example1.png Binary files differnew file mode 100644 index 0000000..ec8c7ff --- /dev/null +++ b/doc/src/images/trafficlight-example1.png diff --git a/doc/src/images/trafficlight-example2.png b/doc/src/images/trafficlight-example2.png Binary files differnew file mode 100644 index 0000000..a12e4db --- /dev/null +++ b/doc/src/images/trafficlight-example2.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 49dfafd..4ead9e4 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -85,12 +85,6 @@ \endif \endif - \if defined(opensourceedition) - \bold{Note:} This edition is for the development of \l{Qt - Open Source Edition}{Free and Open Source} software only; see - \l{Qt Commercial Editions}. - \endif - \raw HTML <table cellpadding="2" cellspacing="1" border="0" width="100%" bgcolor="#e5e5e5"> <tr> diff --git a/doc/src/known-issues.qdoc b/doc/src/known-issues.qdoc index 60fd63d..91e122f 100644 --- a/doc/src/known-issues.qdoc +++ b/doc/src/known-issues.qdoc @@ -60,11 +60,10 @@ \section2 Intel Compiler Support - Although it is possible to build applications against Qt 4.5.0 using Intel - CC 10, these applications will crash when run. A fix for this issue is - scheduled for Qt 4.5.1. We recommend that developers who rely on this - compiler wait until the fix is applied before upgrading to the Qt 4.5.x - series of releases. + Although it is possible to build applications against Qt 4.5.x using Intel + CC 10, these applications will crash when run. We recommend that developers + who rely on this compiler wait until a fix is available before upgrading to + the Qt 4.5.x series of releases. \section2 X11 Hardware Support diff --git a/doc/src/layout.qdoc b/doc/src/layout.qdoc index 38163c8..55dfd8b 100644 --- a/doc/src/layout.qdoc +++ b/doc/src/layout.qdoc @@ -371,7 +371,7 @@ should store the value in a local variable if you need it again later within in the same function. \o You should not call QLayoutItem::setGeometry() twice on the same - item in the smae function. This call can be very expensive if the + item in the same function. This call can be very expensive if the item has several child widgets, because the layout manager must do a complete layout every time. Instead, calculate the geometry and then set it. (This does not only apply to layouts, you should do diff --git a/doc/src/licenses.qdoc b/doc/src/licenses.qdoc index b42b882..1c3f6d2 100644 --- a/doc/src/licenses.qdoc +++ b/doc/src/licenses.qdoc @@ -239,6 +239,24 @@ \o Parts of the internal QImageSmoothScaler::scale() function use code based on pnmscale.c by Jef Poskanzer. \endlist + + \hr + + jQuery JavaScript Library v1.3.2 + http://jquery.com/ + + Copyright (c) 2009 John Resig + Dual licensed under the MIT and GPL licenses. + http://docs.jquery.com/License + + Sizzle CSS Selector Engine - v0.9.3 + Copyright 2009, The Dojo Foundation + Released under the MIT, BSD, and GPL Licenses. + More information: http://sizzlejs.com/ + + \list + \o examples/webkit/fancybrowser/jquery.min.js + \endlist */ /*! diff --git a/doc/src/phonon-api.qdoc b/doc/src/phonon-api.qdoc index 3d04c68..501b5a5 100644 --- a/doc/src/phonon-api.qdoc +++ b/doc/src/phonon-api.qdoc @@ -4457,12 +4457,12 @@ */ /*! - \fn QList<int> Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, HideAdvancedDevicesOverride override = FromSettings) const + \fn QList<int> Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const \internal */ /*! - \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category) const + \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const \internal */ diff --git a/doc/src/porting4.qdoc b/doc/src/porting4.qdoc index c8a9e2b..b93e139 100644 --- a/doc/src/porting4.qdoc +++ b/doc/src/porting4.qdoc @@ -457,6 +457,7 @@ \row \o QToolButton::offIconSet \o Use the \l{QIcon::Off}{off component} of QAbstractButton::icon instead. \row \o QToolButton::onIconSet \o Use the \l{QIcon::On}{on component} of QAbstractButton::icon instead. \row \o QWidget::microFocusHint \o N/A + \row \o QMimeSource::serialNumber () \o N/A \endtable \omit diff --git a/doc/src/properties.qdoc b/doc/src/properties.qdoc index 0775b12..d934f13 100644 --- a/doc/src/properties.qdoc +++ b/doc/src/properties.qdoc @@ -89,7 +89,12 @@ and QWidget::setCursor(), and it also has a \c RESET function, QWidget::unsetCursor(), since no call to QWidget::setCursor() can mean \e {reset to the context specific cursor}. The \c RESET - function musrt return void and take no parameters. + function must return void and take no parameters. + + \o A \c NOTIFY signal is optional. If defined, the signal will be + emitted whenever the value of the property changes. The signal must + take one parameter, which must be of the same type as the property; the + parameter will take the new value of the property. \o The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., diff --git a/doc/src/qmake-manual.qdoc b/doc/src/qmake-manual.qdoc index 39581a2..172bc60 100644 --- a/doc/src/qmake-manual.qdoc +++ b/doc/src/qmake-manual.qdoc @@ -932,6 +932,7 @@ \o \l{qmake Variable Reference#QT}{QT} \o \l{qmake Variable Reference#RCC_DIR}{RCC_DIR} \o \l{qmake Variable Reference#REQUIRES}{REQUIRES} + \o \l{qmake Variable Reference#RESOURCES}{RESOURCES} \o \l{qmake Variable Reference#SOURCES}{SOURCES} \o \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} \o \l{qmake Variable Reference#TARGET}{TARGET} @@ -2420,6 +2421,12 @@ This is mainly used in Qt's build system for building the examples. + \section1 RESOURCES + + This variable contains the name of the resource collection file (qrc) + for the application. Further information about the resource collection + file can be found at \l{The Qt Resource System}. + \section1 RES_FILE This variable contains the name of the resource file for the application. diff --git a/doc/src/qtwebkit.qdoc b/doc/src/qtwebkit.qdoc deleted file mode 100644 index 0092950..0000000 --- a/doc/src/qtwebkit.qdoc +++ /dev/null @@ -1,189 +0,0 @@ -/*! - \module QtWebKit - \title QtWebKit Module - \contentspage Qt's Modules - \previouspage QtSvg - \nextpage QtXml - \ingroup architecture - \ingroup modules - \brief An introduction to the QtWebKit module. - - \keyword Browser - \keyword Web Browser - - \since 4.4 - - QtWebKit provides a Web browser engine that makes it easy to embed content - from the World Wide Web into your Qt application. At the same time Web - content can be enhanced with native controls. - - QtWebKit provides facilities for rendering of HyperText Markup Language - (HTML), Extensible HyperText Markup Language (XHTML) and Scalable Vector - Graphics (SVG) documents, styled using Cascading Style Sheets (CSS) and - scripted with JavaScript. - - A bridge between the JavaScript execution environment and the Qt object - model makes it possible for custom QObjects to be scripted. Integration - with the Qt networking module enables Web pages to be transparently loaded - from Web servers, the local file system or even the Qt resource system. - - In addition to providing pure rendering features, HTML documents can be - made fully editable to the user through the use of the \c{contenteditable} - attribute on HTML elements. - - QtWebKit is based on the Open Source WebKit engine. More information about - WebKit itself can be found on the \l{WebKit Open Source Project} Web site. - - The QtWebKit module is part of the \l{Qt Full Framework Edition}, and the - \l{Open Source Versions of Qt}. - - \note Building the QtWebKit module with debugging symbols is problematic - on many platforms due to the size of the WebKit engine. We recommend - building the module in release mode only for embedded platforms. - - \note Web site icons, also known as "FavIcons", are currently not supported - on Windows. We plan to address this in a future release. - - \note WebKit has certain minimum requirements that must be met on - Embedded Linux systems. See the \l{Qt for Embedded Linux Requirements} - document for more information. - - Topics: - - \tableofcontents - - \section1 Configuring the Build Process - - Applications that use QtWebKit's classes need to be configured to be built - against the QtWebKit module. The following declaration in a \c qmake - project file ensures that an application is compiled and linked - appropriately: - - \snippet doc/src/snippets/code/doc_src_qtwebkit.qdoc 0 - - This line is necessary because only the QtCore and QtGui modules are used - in the default build process. - - To include the definitions of the module's classes, use the following - directive: - - \snippet doc/src/snippets/code/doc_src_qtwebkit.qdoc 1 - - \section1 Architecture - - The easiest way to render content is through the QWebView class. As a - widget it can be embedded into your forms or a graphics view, and it - provides convenience functions for downloading and rendering web sites. - - \snippet snippets/webkit/simple/main.cpp Using QWebView - - QWebView acts as a view onto Web pages, each of which is represented by an - instance of the QWebPage class. QWebPage provides access to the document - structure in a page, describing features such as frames, the navigation - history, and the undo/redo stack for editable content. - - HTML documents can be nested using frames in a frameset. An individual - frame in HTML is represented using the QWebFrame class. It includes the - bridge to the JavaScript window object and can be painted using QPainter. - Each QWebPage has one QWebFrame object as its main frame. - - Individual browser features, defaults and other settings can be configured - through the QWebSettings class. It is possible to provide defaults for all - QWebPage instances through the default settings. Individual attributes - can be overidden by the page specific settings object. - - \section1 Netscape Plugin Support - - Since WebKit supports the Netscape Plugin API, Qt applications can display - Web pages that embed common plugins, as long as the user has the appropriate - binary files for those plugins installed. - - The following locations are searched for plugins: - - \table - \header \o Linux/Unix \o Windows - \row \o{1,3} - \list - \o \c{.mozilla/plugins} in the user's home directory - \o \c{.netscape/plugins} in the user's home directory - \o System locations, such as - \list - \o \c{/usr/lib/browser/plugins} - \o \c{/usr/local/lib/mozilla/plugins} - \o \c{/usr/lib/firefox/plugins} - \o \c{/usr/lib64/browser-plugins} - \o \c{/usr/lib/browser-plugins} - \o \c{/usr/lib/mozilla/plugins} - \o \c{/usr/local/netscape/plugins} - \o \c{/opt/mozilla/plugins} - \o \c{/opt/mozilla/lib/plugins} - \o \c{/opt/netscape/plugins} - \o \c{/opt/netscape/communicator/plugins} - \o \c{/usr/lib/netscape/plugins} - \o \c{/usr/lib/netscape/plugins-libc5} - \o \c{/usr/lib/netscape/plugins-libc6} - \o \c{/usr/lib64/netscape/plugins} - \o \c{/usr/lib64/mozilla/plugins} - \endlist - \o Locations specified by environment variables: - \list - \o \c{$MOZILLA_HOME/plugins} - \o \c{$MOZ_PLUGIN_PATH} - \o \c{$QTWEBKIT_PLUGIN_PATH} - \endlist - \endlist - - \o - \list - \o The user's \c{Application Data\Mozilla\plugins} directory - \o Standard system locations of plugins for Quicktime, Flash, etc. - \endlist - - \row - \raw HTML - <th class="qt-style">Mac OS X</th> - \endraw - \row - \o - \list - \o \c{Library/Internet Plug-Ins} in the user's home directory - \o The system \c{/Library/Internet Plug-Ins} directory - \endlist - \endtable - - \section1 License Information - - This is a snapshot of the Qt port of WebKit. The exact version information - can be found in the \c{src/3rdparty/webkit/VERSION} file supplied with Qt. - - Qt Commercial Edition licensees that wish to distribute applications that - use the QtWebKit module need to be aware of their obligations under the - GNU Lesser General Public License (LGPL). - - Developers using the Open Source Edition can choose to redistribute - the module under the appropriate version of the GNU LGPL; version 2.1 - for applications and libraries licensed under the GNU GPL version 2, - or version 3 for applications and libraries licensed under the GNU - GPL version 2. - - \legalese - WebKit is licensed under the GNU Library General Public License. - Individual contributor names and copyright dates can be found - inline in the code. - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. - \endlegalese -*/ diff --git a/doc/src/snippets/code/doc_src_properties.qdoc b/doc/src/snippets/code/doc_src_properties.qdoc index ba7f79b..377cc9c 100644 --- a/doc/src/snippets/code/doc_src_properties.qdoc +++ b/doc/src/snippets/code/doc_src_properties.qdoc @@ -3,6 +3,7 @@ Q_PROPERTY(type name READ getFunction [WRITE setFunction] [RESET resetFunction] + [NOTIFY notifySignal] [DESIGNABLE bool] [SCRIPTABLE bool] [STORED bool] diff --git a/doc/src/snippets/code/doc_src_qtestlib.qdoc b/doc/src/snippets/code/doc_src_qtestlib.qdoc index ff52b2f..a0e4944 100644 --- a/doc/src/snippets/code/doc_src_qtestlib.qdoc +++ b/doc/src/snippets/code/doc_src_qtestlib.qdoc @@ -61,7 +61,7 @@ void TestQString::toUpper() //! [9] -/myTestDirectory$ qmake -project "QT += testlib" +/myTestDirectory$ qmake -project "CONFIG += qtestlib" /myTestDirectory$ qmake /myTestDirectory$ make //! [9] diff --git a/doc/src/snippets/code/doc_src_qtwebkit.qdoc b/doc/src/snippets/code/doc_src_qtwebkit.qdoc deleted file mode 100644 index d4fc2bd..0000000 --- a/doc/src/snippets/code/doc_src_qtwebkit.qdoc +++ /dev/null @@ -1,8 +0,0 @@ -//! [0] -QT += webkit -//! [0] - - -//! [1] -#include <QtWebKit> -//! [1] diff --git a/doc/src/snippets/code/src_3rdparty_webkit_WebKit_qt_Api_qwebview.cpp b/doc/src/snippets/code/src_3rdparty_webkit_WebKit_qt_Api_qwebview.cpp deleted file mode 100644 index f04cd29..0000000 --- a/doc/src/snippets/code/src_3rdparty_webkit_WebKit_qt_Api_qwebview.cpp +++ /dev/null @@ -1,35 +0,0 @@ - -void wrapInFunction() -{ - -//! [0] - view->page()->history(); -//! [0] - - -//! [1] - view->page()->settings(); -//! [1] - - -//! [2] - view->triggerAction(QWebPage::Copy); -//! [2] - - -//! [3] - view->page()->triggerPageAction(QWebPage::Stop); -//! [3] - - -//! [4] - view->page()->triggerPageAction(QWebPage::GoBack); -//! [4] - - -//! [5] - view->page()->triggerPageAction(QWebPage::GoForward); -//! [5] - -} - diff --git a/doc/src/snippets/code/src_qdbus_qdbusargument.cpp b/doc/src/snippets/code/src_qdbus_qdbusargument.cpp index b982510..efd54ac 100644 --- a/doc/src/snippets/code/src_qdbus_qdbusargument.cpp +++ b/doc/src/snippets/code/src_qdbus_qdbusargument.cpp @@ -4,7 +4,7 @@ struct MyStructure int count; QString name; }; -QT_DECLARE_METATYPE(MyStructure) +Q_DECLARE_METATYPE(MyStructure) // Marshall the MyStructure data into a D-Bus argument QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) diff --git a/doc/src/snippets/sqldatabase/sqldatabase.cpp b/doc/src/snippets/sqldatabase/sqldatabase.cpp index ae176ac..06afa0c 100644 --- a/doc/src/snippets/sqldatabase/sqldatabase.cpp +++ b/doc/src/snippets/sqldatabase/sqldatabase.cpp @@ -524,7 +524,7 @@ protected: bool fetchLast() { return false; } int size() { return 0; } int numRowsAffected() { return 0; } - QSqlRecord record() { return QSqlRecord(); } + QSqlRecord record() const { return QSqlRecord(); } }; //! [47] diff --git a/doc/src/snippets/webkit/simple/simple.pro b/doc/src/snippets/webkit/simple/simple.pro deleted file mode 100644 index 61cd3bf..0000000 --- a/doc/src/snippets/webkit/simple/simple.pro +++ /dev/null @@ -1,2 +0,0 @@ -QT += webkit -SOURCES = main.cpp diff --git a/doc/src/snippets/webkit/webpage/main.cpp b/doc/src/snippets/webkit/webpage/main.cpp deleted file mode 100644 index b433ac2..0000000 --- a/doc/src/snippets/webkit/webpage/main.cpp +++ /dev/null @@ -1,62 +0,0 @@ -#include <QtGui> -#include <QWebPage> -#include <QWebFrame> - -//! [0] -class Thumbnailer : public QObject -{ - Q_OBJECT - -public: - Thumbnailer(const QUrl &url); - -signals: - void finished(); - -private slots: - void render(); - -private: - QWebPage page; - -}; -//! [0] - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - - Thumbnailer thumbnail(QUrl("http://qtsoftware.com")); - - QObject::connect(&thumbnail, SIGNAL(finished()), - &app, SLOT(quit())); - - return app.exec(); -} - -//! [1] -Thumbnailer::Thumbnailer(const QUrl &url) -{ - page.mainFrame()->load(url); - connect(&page, SIGNAL(loadFinished(bool)), - this, SLOT(render())); -} -//! [1] - -//! [2] -void Thumbnailer::render() -{ - page.setViewportSize(page.mainFrame()->contentsSize()); - QImage image(page.viewportSize(), QImage::Format_ARGB32); - QPainter painter(&image); - - page.mainFrame()->render(&painter); - painter.end(); - - QImage thumbnail = image.scaled(400, 400); - thumbnail.save("thumbnail.png"); - - emit finished(); -} -//! [2] -#include "main.moc" diff --git a/doc/src/snippets/webkit/webpage/webpage.pro b/doc/src/snippets/webkit/webpage/webpage.pro deleted file mode 100644 index fcad03b..0000000 --- a/doc/src/snippets/webkit/webpage/webpage.pro +++ /dev/null @@ -1,3 +0,0 @@ -CONFIG += console -QT += webkit -SOURCES = main.cpp
\ No newline at end of file diff --git a/doc/src/statemachine.qdoc b/doc/src/statemachine.qdoc index 60ae815..27bd4f8 100644 --- a/doc/src/statemachine.qdoc +++ b/doc/src/statemachine.qdoc @@ -1,11 +1,41 @@ /**************************************************************************** ** -** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** Contact: Qt Software Information (qt-info@nokia.com) ** -** This file is part of the $MODULE$ of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** -** $TROLLTECH_DUAL_LICENSE$ +** $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$ ** ****************************************************************************/ @@ -13,6 +43,7 @@ \page statemachine-api.html \title The State Machine Framework \brief An overview of the State Machine framework for constructing and executing state graphs. + \ingroup architecture \tableofcontents @@ -33,10 +64,10 @@ The State Machine framework provides an API and execution model that can be used to effectively embed the elements and semantics of statecharts in Qt - applications. The framework integrates tightly with Qt's existing event - system and meta-object system; for example, transitions between states can - be triggered by signals, and states can be configured to set properties and - invoke methods on QObjects. + applications. The framework integrates tightly with Qt's meta-object system; + for example, transitions between states can be triggered by signals, and + states can be configured to set properties and invoke methods on QObjects. + Qt's event system is used to drive the state machines. \section1 A Simple State Machine @@ -52,34 +83,49 @@ \endomit The following snippet shows the code needed to create such a state machine. + First, we create the state machine and states: \code QStateMachine machine; QState *s1 = new QState(); QState *s2 = new QState(); QState *s3 = new QState(); + \endcode + + Then, we create the transitions by using the QState::addTransition() + function: + \code s1->addTransition(button, SIGNAL(clicked()), s2); s2->addTransition(button, SIGNAL(clicked()), s3); s3->addTransition(button, SIGNAL(clicked()), s1); + \endcode + + Next, we add the states to the machine and set the machine's initial state: + \code machine.addState(s1); machine.addState(s2); machine.addState(s3); machine.setInitialState(s1); + \endcode + Finally, we start the state machine: + + \code machine.start(); \endcode - Once the state machine has been set up, you need to start it by calling - QStateMachine::start(). The state machine executes asynchronously, i.e. it - becomes part of your application's event loop. + The state machine executes asynchronously, i.e. it becomes part of your + application's event loop. + + \section1 Doing Useful Work on State Entry and Exit - The above state machine is perfectly fine, but it doesn't \e do anything; it - merely transitions from one state to another. The QState::assignProperty() - function can be used to have a state set a property of a QObject when the - state is entered. In the following snippet, the value that should be - assigned to a QLabel's text property is specified for each state: + The above state machine merely transitions from one state to another, it + doesn't perform any operations. The QState::assignProperty() function can be + used to have a state set a property of a QObject when the state is + entered. In the following snippet, the value that should be assigned to a + QLabel's text property is specified for each state: \code s1->assignProperty(label, "text", "In state s1"); @@ -90,20 +136,26 @@ When any of the states is entered, the label's text will be changed accordingly. - The QActionState::entered() signal is emitted when the state is entered. In the + The QState::entered() signal is emitted when the state is entered, and the + QState::exited() signal is emitted when the state is exited. In the following snippet, the button's showMaximized() slot will be called when - state \c s3 is entered: + state \c s3 is entered, and the button's showMinimized() slot will be called + when \c s3 is exited: \code QObject::connect(s3, SIGNAL(entered()), button, SLOT(showMaximized())); + QObject::connect(s3, SIGNAL(exited()), button, SLOT(showMinimized())); \endcode - \section1 Sharing Transitions By Grouping States + \section1 State Machines That Finish The state machine defined in the previous section never finishes. In order for a state machine to be able to finish, it needs to have a top-level \e - final state. When the state machine enters a top-level final state, the - machine will emit the finished() signal and halt. + final state (QFinalState object). When the state machine enters a top-level + final state, the machine will emit the QStateMachine::finished() signal and + halt. + + \section1 Sharing Transitions By Grouping States Assume we wanted the user to be able to quit the application at any time by clicking a Quit button. In order to achieve this, we need to create a final @@ -165,6 +217,9 @@ s12>addTransition(quitButton, SIGNAL(clicked()), s12); \endcode + A transition can have any state as its target, i.e. the target state does + not have to be on the same level in the state hierarchy as the source state. + \section1 Using History States to Save and Restore the Current State Imagine that we wanted to add an "interrupt" mechanism to the example @@ -251,10 +306,16 @@ QState *s12 = new QState(s1); \endcode + When a parallel state group is entered, all its child states will be + simultaneously entered. Transitions within the individual child states + operate normally. However, any of the child states may take a transition + outside the parent state. When this happens, the parent state and all of its + child states are exited. + \section1 Detecting that a Composite State has Finished - A child state can be final; when a final child state is entered, the parent - state emits the QState::finished() signal. + A child state can be final (a QFinalState object); when a final child state + is entered, the parent state emits the QState::finished() signal. \img statemachine-finished.png \omit @@ -263,7 +324,287 @@ This is useful when you want to hide the internal details of a state; i.e. the only thing the outside world should be able to do is enter the - state, and get a notification when the state has finished (i.e. when a final - child state has been entered). + state, and get a notification when the state has completed its work. + + For parallel state groups, the QState::finished() signal is emitted when \e + all the child states have entered final states. + + \section1 Events, Transitions and Guards + + A QStateMachine runs its own event loop. For signal transitions + (QSignalTransition objects), QStateMachine automatically posts a + QSignalEvent to itself when it intercepts the corresponding signal; + similarly, for QObject event transitions (QEventTransition objects) a + QWrappedEvent is posted. + + You can post your own events to the state machine using + QStateMachine::postEvent(). + + When posting a custom event to the state machine, you typically also have + one or more custom transitions that can be triggered from events of that + type. To create such a transition, you subclass QAbstractTransition and + reimplement QAbstractTransition::eventTest(), where you check if an event + matches your event type (and optionally other criteria, e.g. attributes of + the event object). + + Here we define our own custom event type, \c StringEvent, for posting + strings to the state machine: + + \code + struct StringEvent : public QEvent + { + StringEvent(const QString &val) + : QEvent(QEvent::Type(QEvent::User+1)), + value(val) {} + + QString value; + }; + \endcode + + Next, we define a transition that only triggers when the event's string + matches a particular string (a \e guarded transition): + + \code + class StringTransition : public QAbstractTransition + { + public: + StringTransition(const QString &value) + : m_value(value) {} + + protected: + virtual bool eventTest(QEvent *e) const + { + if (e->type() != QEvent::Type(QEvent::User+1)) // StringEvent + return false; + StringEvent *se = static_cast<StringEvent*>(e); + return (m_value == se->value); + } + + virtual void onTransition(QEvent *) {} + + private: + QString m_value; + }; + \endcode + + In the eventTest() reimplementation, we first check if the event type is the + desired one; if so, we cast the event to a StringEvent and perform the + string comparison. + + The following is a statechart that uses the custom event and transition: + + \img statemachine-customevents.png + \omit + \caption This is a caption + \endomit + + Here's what the implementation of the statechart looks like: + + \code + QStateMachine machine; + QState *s1 = new QState(); + QState *s2 = new QState(); + QFinalState *done = new QFinalState(); - */ + StringTransition *t1 = new StringTransition("Hello"); + t1->setTargetState(s2); + s1->addTransition(t1); + StringTransition *t2 = new StringTransition("world"); + t2->setTargetState(done); + s2->addTransition(t2); + + machine.addState(s1); + machine.addState(s2); + machine.addState(done); + machine.setInitialState(s1); + \endcode + + Once the machine is started, we can post events to it. + + \code + machine.postEvent(new StringEvent("Hello")); + machine.postEvent(new StringEvent("world")); + \endcode + + \section1 Using Restore Policy To Automatically Restore Properties + + In some state machines it can be useful to focus the attention on assigning properties in states, + not on restoring them when the state is no longer active. If you know that a property should + always be restored to its initial value when the machine enters a state that does not explicitly + give the property a value, you can set the global restore policy to + QStateMachine::RestoreProperties. + + \code + QStateMachine machine; + machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); + \endcode + + When this restore policy is set, the machine will automatically restore all properties. If it + enters a state where a given property is not set, it will first search the hierarchy of ancestors + to see if the property is defined there. If it is, the property will be restored to the value + defined by the closest ancestor. If not, it will be restored to its initial value (i.e. the + value of the property before any property assignments in states were executed.) + + Take the following code: + \code + QStateMachine machine; + machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); + + QState *s1 = new QState(); + s1->assignProperty(object, "fooBar", 1.0); + machine.addState(s1); + machine.setInitialState(s1); + + QState *s2 = new QState(); + machine.addState(s2); + \endcode + + Lets say the property \c fooBar is 0.0 when the machine starts. When the machine is in state + \c s1, the property will be 1.0, since the state explicitly assigns this value to it. When the + machine is in state \c s2, no value is explicitly defined for the property, so it will implicitly + be restored to 0.0. + + If we are using nested states, the parent defines a value for the property which is inherited by + all descendants that do not explicitly assign a value to the property. + \code + QStateMachine machine; + machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); + + QState *s1 = new QState(); + s1->assignProperty(object, "fooBar", 1.0); + machine.addState(s1); + machine.setInitialState(s1); + + QState *s2 = new QState(s1); + s2->assignProperty(object, "fooBar", 2.0); + s1->setInitialState(s2); + + QState *s3 = new QState(s1); + \endcode + + Here \c s1 has two children: \c s2 and \c s3. When \c s2 is entered, the property \c fooBar + will have the value 2.0, since this is explicitly defined for the state. When the machine is in + state \c s3, no value is defined for the state, but \c s1 defines the property to be 1.0, so this + is the value that will be assigned to \c fooBar. + + \section1 Animating Property Assignments + + The State Machine API connects with the Animation API in Qt to allow automatically animating + properties as they are assigned in states. + + Say we have the following code: + \code + QState *s1 = new QState(); + QState *s2 = new QState(); + + s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); + s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100)); + + s1->addTransition(button, SIGNAL(clicked()), s2); + \endcode + + Here we define two states of a user interface. In \c s1 the \c button is small, and in \c s2 + it is bigger. If we click the button to transition from \c s1 to \c s2, the geometry of the button + will be set immediately when a given state has been entered. If we want the transition to be + smooth, however, all we need to do is make a QPropertyAnimation and add this to the transition + object. + + \code + QState *s1 = new QState(); + QState *s2 = new QState(); + + s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); + s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100)); + + QSignalTransition *transition = s1->addTransition(button, SIGNAL(clicked()), s2); + transition->addAnimation(new QPropertyAnimation(button, "geometry")); + \endcode + + Adding an animation for the property in question means that the property assignment will no + longer take immediate effect when the state has been entered. Instead, the animation will start + playing when the state has been entered and smoothly animate the property assignment. Since we + do not set the start value or end value of the animation, these will be set implicitly. The + start value of the animation will be the property's current value when the animation starts, and + the end value will be set based on the property assignments defined for the state. + + If the global restore policy of the state machine is set to QStateMachine::RestoreProperties, + it is possible to also add animations for the property restorations. + + \section1 Detecting That All Properties Have Been Set In A State + + When animations are used to assign properties, a state no longer defines the exact values that a + property will have when the machine is in the given state. While the animation is running, the + property can potentially have any value, depending on the animation. + + In some cases, it can be useful to be able to detect when the property has actually been assigned + the value defined by a state. For this, we can use the state's polished() signal. + \code + QState *s1 = new QState(); + s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); + + QState *s2 = new QState(); + + s1->addTransition(s1, SIGNAL(polished()), s2); + \endcode + + The machine will be in state \c s1 until the \c geometry property has been set. Then it will + immediately transition into \c s2. If the transition into \c s1 has an animation for the \c + geometry property, then the machine will stay in \c s1 until the animation has finished. If there + is no animation, it will simply set the property and immediately enter state \c s2. + + Either way, when the machine is in state \c s2, the property \c geometry has been assigned the + defined value. + + If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit + the polished() signal until these have been executed as well. + + \section1 What happens if a state is exited before the animation has finished + + If a state has property assignments, and the transition into the state has animations for the + properties, the state can potentially be exited before the properties have been assigned to the + values defines by the state. This is true in particular when there are transitions out from the + state that do not depend on the state being polished, as described in the previous section. + + The State Machine API guarantees that a property assigned by the state machine either: + \list + \o Has a value explicitly assigned to the property. + \o Is currently being animated into a value explicitly assigned to the property. + \endlist + + When a state is exited prior to the animation finishing, the behavior of the state machine depends + on the target state of the transition. If the target state explicitly assigns a value to the + property, no additional action will be taken. The property will be assigned the value defined by + the target state. + + If the target state does not assign any value to the property, there are two + options: By default, the property will be assigned the value defined by the state it is leaving + (the value it would have been assigned if the animation had been permitted to finish playing.) If + a global restore policy is set, however, this will take precedence, and the property will be + restored as usual. + + \section1 Default Animations + + As described earlier, you can add animations to transitions to make sure property assignments + in the target state are animated. If you want a specific animation to be used for a given property + regardless of which transition is taken, you can add it as a default animation to the state + machine. This is in particular useful when the properties assigned (or restored) by specific + states is not known when the machine is constructed. + + \code + QState *s1 = new QState(); + QState *s2 = new QState(); + + s2->assignProperty(object, "fooBar", 2.0); + s1->addTransition(s2); + + QStateMachine machine; + machine.setInitialState(s1); + machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar")); + \endcode + + When the machine is in state \c s2, the machine will play the default animation for the + property \c fooBar since this property is assigned by \c s2. + + Note that animations explicitly set on transitions will take precedence over any default + animation for the given property. +*/ |
