diff options
author | Martin Jones <martin.jones@nokia.com> | 2009-04-30 03:26:05 (GMT) |
---|---|---|
committer | Martin Jones <martin.jones@nokia.com> | 2009-04-30 03:26:05 (GMT) |
commit | 0ee6bf1226f3069f117d0b0b75df14ddf38e75de (patch) | |
tree | 01a63f8585790624e1746ba1b43cd91731699e42 /doc | |
parent | 0a4b78de06b60a5fc0a9182687ded099968c4055 (diff) | |
parent | 0282ea19722c247157c652ef9122379f0e715497 (diff) | |
download | Qt-0ee6bf1226f3069f117d0b0b75df14ddf38e75de.zip Qt-0ee6bf1226f3069f117d0b0b75df14ddf38e75de.tar.gz Qt-0ee6bf1226f3069f117d0b0b75df14ddf38e75de.tar.bz2 |
Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui
Diffstat (limited to 'doc')
22 files changed, 478 insertions, 492 deletions
diff --git a/doc/doc.pri b/doc/doc.pri index 46df3cb..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/ } } diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 8fff472..8955587 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -16,7 +16,7 @@ The following table lists the Qml elements provided by the Qt Declarative module \o \list -\o \l StateGroup +\o \l State \o \l SetProperty \o \l SetProperties \o \l ParentChange diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 17fda4d..e65808f 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -17,10 +17,14 @@ directory, bin/duiviewer $QT_SOURCE_DIR/examples/declarative/mediabrowser/mediabrowser.qml \endcode -Many other simple demos can be found under the \c examples/declarative sub +Many other simple examples can be found under the \c examples/declarative sub directory. Some can be run directly using the viewer like those above, and others require you to build and run an executable. +More sophisticated demos of large applications can be found under the \c demos/declarative +sub directory. These are intended to show more integrated functionality rather than +to be instructive on specific elements. + Finally, check out the \l {tutorial} to learn a little more about writing your own QML-based applications. diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc index b750aa0..06d7727 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 @@ -354,6 +355,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/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/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/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/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/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/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/qnamespace.qdoc b/doc/src/qnamespace.qdoc index d9f001e..097333b 100644 --- a/doc/src/qnamespace.qdoc +++ b/doc/src/qnamespace.qdoc @@ -129,13 +129,8 @@ Therefore, if it is important to minimize resource consumption, do not set this attribute. - \value AA_MSWindowsUseDirect3DByDefault Is a Windows specific - attribute, that will make the Direct3D paint engine the - default Qt widget paint engine. Note that you can toggle - usage of the Direct3D engine on individual QWidgets by - setting/clearing the \c WA_MSWindowsUseDirect3D attribute - on a specific widget. \bold {This functionality is - experimental}. + \value AA_MSWindowsUseDirect3DByDefault This value is obsolete and + has no effect. \value AA_DontShowIconsInMenus Actions with the Icon property won't be shown in any menus unless specifically set by the @@ -948,10 +943,8 @@ position. This is set/cleared by QWidget::move() and by QWidget::setGeometry(). - \value WA_MSWindowsUseDirect3D Makes drawing to a widget - with this attribute set use the Direct3D paint engine, if the - Direct3D paint engine is available. \bold {This functionality - is experimental.} + \value WA_MSWindowsUseDirect3D This value is obsolete and has no + effect. \value WA_NoBackground This value is obsolete. Use WA_OpaquePaintEvent instead. 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_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/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/tutorials/declarative.qdoc b/doc/src/tutorials/declarative.qdoc index be8fad9..3724b10 100644 --- a/doc/src/tutorials/declarative.qdoc +++ b/doc/src/tutorials/declarative.qdoc @@ -80,9 +80,9 @@ This means you should use the duiviewer application provided with Qt to run the examples. - \list 1 + \list \o \l{tutorials/declarative/contacts/part1}{Drawing and Animation} - \o \l{tutorials/declarative/contacts/part2}{Reuse of QML components} + \o \l{tutorials/declarative/contacts/part2}{Reusing QML Components} \o \l{tutorials/declarative/contacts/part3}{Models, Views and Delegates} \o \l{tutorials/declarative/contacts/part4}{Other Tricks} \endlist @@ -121,27 +121,14 @@ \image declarative-roundrect.png - \code - <Rect id="removeButton" - width="30" height="30" - color="red" - radius="5"/> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/1/RemoveButton.qml 0 This is the simplest of QML components. It describes a rectangle with some simple properties. In QML all components start with a capital letter, and their properties with lower case letters. Properties can either be declared as XML attributes or as children of the - component element. The above rectangle could equally be written + component element. - \code - <Rect id="removeButton" color="red"> - <width>30</width> - <height>30</height> - <radius>5</radius> - </Rect> - \endcode - The rectangle component is one of the more simple QML components. Apart from the properties all QML components share, it has the properties @@ -183,18 +170,7 @@ \image declarative-removebutton-close.png - \code - <Rect id="removeButton" - width="30" height="30" - color="red" - radius="5"> - <Image id="trashIcon" - width="22" height="22" - anchors.right="{parent.right}" anchors.rightMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/trash.png"/> - </Rect> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/2/RemoveButton.qml 0 The trashIcon image is added as a child of the Rectangle. In this case the <children> tag isn't used because the default property of the @@ -202,20 +178,7 @@ and use some other default component, when this is the case its possible to explicitly list the sub component as a child as follows: - \code - <Rect id="removeButton" - width="30" height="30" - color="red" - radius="5"> - <children> - <Image id="trashIcon" - width="22" height="22" - anchors.right="{parent.right}" anchors.rightMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/trash.png"/> - </children> - </Rect> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/2a/RemoveButton.qml 0 The Image element allows loading an image file for display. The source specified is a URL, and in this case refers to a portable network graphics @@ -252,31 +215,7 @@ This is a wider rectangle with two images and some text. The code to draw this state of the button could be written as follows: - \code - <Rect id="removeButton" - width="230" height="30" - color="red" - radius="5"> - <Image id="cancelIcon" - width="22" height="22" - anchors.right="{parent.right}" anchors.rightMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/cancel.png"/> - <Image id="confirmIcon" - width="22" height="22" - anchors.left="{parent.left}" anchors.leftMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/ok.png"/> - <Text id="text" - anchors.verticalCenter="{parent.verticalCenter}" - anchors.left="{confirmIcon.right}" anchors.leftMargin="4" - anchors.right="{cancelIcon.left}" anchors.rightMargin="4" - font.bold="true" - color="white" - hAlign="AlignHCenter" - text="Remove"/> - </Rect> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/3/RemoveButton.qml 0 The rectangle with is now wider by 200 pixels. Also the trashIcon has been replaced with the confirm state children. Normally we wouldn't @@ -310,21 +249,32 @@ might look like. \code - <Rect id="removeButton" - width="30" height="30" - color="red" - radius="5"> - <Image id="trashIcon" - width="22" height="22" - anchors.right="{parent.right}" anchors.rightMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/trash.png"/> - <Image id="cancelIcon" - width="22" height="22" - anchors.right="{parent.right}" anchors.rightMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/cancel.png" - opacity="0"/> + Rect { + id: removeButton + width: 30 + height: 30 + color: "red" + radius: 5 + Image { + id: trashIcon + width: 22 + height: 22 + anchors.right: parent.right + anchors.rightMargin: 4 + anchors.verticalCenter: parent.verticalCenter + src: "../../shared/pics/trash.png" + opacity: 1 + } + Image { + id: cancelIcon + width: 22 + height: 22 + anchors.right: parent.right + anchors.rightMargin: 4 + anchors.verticalCenter: parent.verticalCenter + src: "../../shared/pics/cancel.png" + opacity: 0 + } \endcode The code above includes components from both states of the RemoveButton, @@ -335,17 +285,7 @@ should be changed. For the RemoveButton there is only one non-base state required. In this tutorial we will name it the 'opened' state. - \code - <states> - <State name="opened"> - <SetProperty target="{removeButton}" property="width" value="230"/> - <SetProperty target="{text}" property="opacity" value="1"/> - <SetProperty target="{confirmIcon}" property="opacity" value="1"/> - <SetProperty target="{cancelIcon}" property="opacity" value="1"/> - <SetProperty target="{trashIcon}" property="opacity" value="0"/> - </State> - </states> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4/RemoveButton.qml states In the opened state the width of the button itself changes from the base width of 30 to the new width of 230. Also the opacity of the children @@ -357,18 +297,7 @@ To trigger the change we will react to the 'clicked' signal of a MouseRegion component. - \code - <Image id="trashIcon" - width="22" height="22" - anchors.right="{parent.right}" anchors.rightMargin="4" - anchors.verticalCenter="{parent.verticalCenter}" - src="../shared/pics/trash.png" - opacity="1"> - <MouseRegion - anchors.fill="{parent}" - onClicked="toggle()"/> - </Image> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4/RemoveButton.qml mouse region MouseRegion components handle mouse actions within their geometry. This geometry behaves the same way as painted components, such that children @@ -381,7 +310,7 @@ a function called toggle() is called. It might also have been written \code - onClicked="removeButton.state='opened'" + onClicked: { removeButton.state='opened' } \endcode However in this case we are using a function because it allows multiple @@ -391,69 +320,24 @@ The toggle() function is a new function specified as part of the remove button element. - \code - <resources> - <Script> - function toggle() { - print('removeButton.toggle()'); - if (removeButton.state == 'opened') { - removeButton.state = ''; - } else { - removeButton.state = 'opened'; - } - } - </Script> - </resources> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/4/RemoveButton.qml script Any QML component can have a set of resources specified. One of those resources is any Script that might be needed. See the {QtScript Module}{QtScript Module} for more information on how to write - script code in Qt. There are only a couple of additional items to - note when using Script with QML components. The first is that it - is an xml file, that means either CDATA or other forms of escaping - should be used if special characters are needed. For example, - the expression; - - \code - if (a && b) {} - \endcode - - Should either be escaped as: - - \code - if (a && b) {} - \endcode + script code in Qt. - or enclosed in a CDATA section as - - \code - <![CDATA[if (a && b) {}]]> - \endcode - - The other item to note is that you can refer to identified QML components + It is possible to refer to identified QML components within the script. Hence the function for our RemoveButton will check if the state is already open to determine what the new state should be. - We also have added a print function. This isn't required for the button - to function, but is useful for tracking down possible bugs when - working with QML. - - See the file RemoveButton4.qml for the full multi-state specification. - \section1 Animation Currently the RemoveButton is function, but snaps between our two states. Fortunately making the transition between states smooth is very simple. We only need one more bit of code at the end of our removeButton component. - \code - <transitions> - <Transition fromState="*" toState="opened" reversible="true"> - <NumericAnimation properties="opacity,x,width" duration="200"/> - </Transition> - </transitions> - \endcode + \snippet declarative/tutorials/contacts/1_Drawing_and_Animation/5/RemoveButton.qml transition All QML components have a transitions property. This describes how properties of items within the component should change. In this case @@ -462,9 +346,296 @@ to complete their transition. \omit - TODO More on types of animation + TODO More on types of animation, e.g. ColorAnimation, Behaviors. \endomit In the next chapter we will show how we can use the remove button in other QML components. */ + +/*! + \page tutorials-declarative-contacts-part2.html + \contentspage {Declarative UI Tutorial}{Contents} + \previouspage {tutorials/declarative/contacts/part1}{Chapter 1} + \nextpage {tutorials/declarative/contacts/part3}{Chapter 3} + \example tutorials/declarative/contacts/part2 + \title Reusing QML Components + \tableofcontents + + The second part of this tutorial covers how to reuse QML components and + have them interact with each other. The RemoveButton developed in the + previous chapter is intended to be part of a more complex control for + editing a field of our contact. This ContactField in turn is intended + to be used in a contact editing control. + + \section1 Loading QML Components + + Reusing the RemoveButton itself is very simple. When parsing a QML file + if a Component is referred to that isn't already in the system, Qt + will try to load it from a file of the same name with the ".qml" extension. + + \snippet declarative/tutorials/contacts/2_Reuse/1/ContactField.qml load + + The above QML code will attempt to load the RemoveButton component from + a file with the name "RemoveButton.qml" from the following search paths. + + \list + \o Any imported directories. These are listed at the start of the file using + \c { import "path" }. + \o The run directory + \o The run directory + "/qml" + \o the directory of the QML code file + \o the directory of the QML code file + "/qml" + \endlist. + + All the properties of the button are + accessible and can be overridden from defaults. The loaded component + can also refer to elements further up in the tree, so that code within + RemoveButton.qml could refer to the contactField component. However only + properties of the top level element in RemoveButton.qml are visible to + the contact field. In order to allow contact field to modify how wide + the remove button will be when opened we need to add a property to the + remove button. + + \section1 Properties and Signals + + \snippet declarative/tutorials/contacts/2_Reuse/2/RemoveButton.qml define properties and signals + + These properties and signals are accessed from the contact field the same + way standard system components are accessed. + + \snippet declarative/tutorials/contacts/2_Reuse/2/RemoveButton.qml use properties and signals + + Now when the remove button is expanded, it will expand to the width of the + contact field. Also when the user confirms the remove action, the + text section of the contact field will be cleared. When creating a + component that does have children out of its own + bounds its important to consider whether the item should be clipped, + which is done above with \c{clip: true}. + + \section1 States + + Its also possible to access the state of included components. The FieldText + component we will use in this tutorial is also been written specifically + for our contacts application, as was the RemoveButton component. In + this case we want it to expand when editing. One way to do this would + be to anchor the field text component to the center of its parent and + then let its own width change push the remove button away, however that + would make it difficult to have the remove button also push the field + text to the left when the remove button expands. + + So instead we will anchor the right edge of the field text to + the left edge of the remove button and use a state change in the + contact field itself to move the remove button and the field icon out of + view. + + \snippet declarative/tutorials/contacts/2_Reuse/3/RemoveButton.qml all + + Apart from accessing the fieldText.state, the above code also uses the when + attribute of its own editingText state. This is an alternative to using + a signal to change state. When the value of the expression for the + when attribute changes, Qt will detect if the contactField needs to enter + that state. In the FieldText element a similar approach is used to fade + out the label of the FieldText when the user enters some text of their own. + + \snippet declarative/tutorials/contacts/3_Reuse/2/FieldText.qml behavior + + fieldText is the enclosing component and textEdit is a TextEdit element + provided by Qt. In the QML code above, the opacity of the textLabel is + only 1 if there is text for the textEdit is empty. This is a form of + short cut to using states for an element, useful if only one property + is changing as it is for the textLabel. To animate a property change is + similar to animating a state change. Using the Behavior element we can + specify how the property changes if it does change state, allowing for + a smooth transition. + + The fieldText element also handles changes to the text using the + onValueChanged attribute when specifying properties. + + \snippet declarative/tutorials/contacts/2_Reuse/3/FieldText.qml value change + + Because the user needs to be able to edit text in the text edit, it + shouldn't be simply bound to the text property of the FieldText component. + However if a component using the FieldText component sets the text + property of the FieldText component it should in turn set the text + of the text edit. + + \section1 Key and Mouse Focus + + Unlike in Qt setting focus to true on a component does not always mean + that the component has focus. This is due to the declarative nature + of QML, and can be affected by multiple components both indicating + focus to be true. At the time of writing this tutorial both key and mouse + focus handling are still being improved. Hence we will only lightly cover + the topic. + + Normally in QML this is handled by FocusRealm components. A focus realm + is a sort of cut off point for determining focus. If a FocusRealm does + not have focus then any children of it won't be able to get focus even + if they do set focus to true. If your component has multiple child + components that could gain focus ensure that they are guarded by FocusRealm + component, and add code to handle which focus realms have focus + at that level. The alternative and approach done at this stage in + the tutorial is to only have one component set focus to true at a time. + + Currently if multiple contact fields were put into our contact editor, + any of the FieldText components could be clicked and opened, and + any of the RemoveButton components could be clicked and opened, all + at the same time. We would like this behavior to be some what modal + instead, encouraging the user to either accept or cancel the current + action before moving onto a new action. + + In the tutorial we do this with a property of our top level component + to handle whether we are in this state or not. + + \snippet declarative/tutorials/contacts/2_Reuse/4/Contact.qml grab property + + And in the code where we want to check or avoid allowing mouse interaction. + + \snippet declarative/tutorials/contacts/2_Reuse/4/RemoveButton.qml grab + + Handling Key and Mouse focus in QML is quite likely to change before + the Qt 4.6 release. +*/ + +/*! + \page tutorials-declarative-contacts-part3.html + \contentspage {Declarative UI Tutorial}{Contents} + \previouspage {tutorials/declarative/contacts/part2}{Chapter 2} + \nextpage {tutorials/declarative/contacts/part4}{Chapter 4} + \example tutorials/declarative/contacts/part3 + \title Models, Views and Delegates + \tableofcontents + + In the previous chapters we designed a component to display and + edit a contact. The next step is to display a list of those contacts + and allow the user to expand individual contacts for editing. + + As the previous elements will not be changed in this section, they have + been moved to a lib directory for this tutorial and the relevant + name space path has been used. + + \section1 Simple List View + + Displaying lists requires three components. A model that holds the + data displayed, a delegate to indicate how elements are drawn and + a view to arrange the elements. + + For the purposes of this tutorial we will be using an SQL query as our + data model. This can be declared in the resources section of + the parent item. + + \snippet declarative/tutorials/contacts/3_Collections/1/ContactView.qml model + + The SqlConnection component describes how to connect to the database in + much the same ways as the QSqlDatabase::addDatabase() function is used. + In this case an SQLite database is used as it can be connected to as a + file, reducing complexity in setting up a database server or credentials. + + The SqlQuery component allows various forms of queries to be described. + When the query is a select statement, the component also acts as a model + allowing it to provide data to a ListView component. The query above + retrieves the fields recid, label, email and phone from a contacts table, + and orders the results by the label of the contact first, and then by + the recid for any contacts with equivalent labels. + + The ListView component is suitable for displaying models, and is declared + much like any other QML component. However since it might have any number + of child items in the list, it has a property that defines how to construct + components for items when displayed. + + \snippet declarative/tutorials/contacts/3_Collections/1/ContactView.qml delegate + + Unlike a child element, this describes a template on how to build the component + for each element, much in the same way that components are loaded from + files such as RemoveButton.qml. + + The entire view component will look like: + + \snippet declarative/tutorials/contacts/3_Collections/1/ContactView.qml view + + This gives us a list of contacts that the user can flick through. + + .image. + + \section1 Animating Delegates + + The next step is to allow the user to click on a contact to edit the + contact. We will take advantage of QML to open a Contact component + in the list rather than as a new dialog or view. This is very + similar to how the contents of the FieldText and RemoveButton components + are swapped in and out. + + \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml components + + The first step is to have two children of our delegate component that can + be swapped between. The plain Text component and the Contact component built + in the previous chapters. We also add a MouseRegion that can be clicked upon + to change the state of the delegate component. + + \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml states + + This defines the open state of the delegate. It changes the height of the delegate + component to that of the whole list view, pushing the other items off each end of + the list. It sets the lists views scroll yPosition of the ListView to the + y value of the delegate so that the top of the delegate matches the top of the list view. + The next step is to lock the list view. This prevents the user being able to flick + the list view, meaning while in this state the delegate will continue to + fill the ListView's visible area. The final to properties that are set should + be familiar from previous chapters, setting the opacity of the items such + that the new item is visible and the old item hidden. + + We then add a transition so that this becomes animated: + + \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml transition + + This allows the user to click on an item to enter the open state. + + .image. + + Elsewhere on our contact view we add a button so that the user can leave the + detailed view of the contact. + \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml button + + And connect it's clicked value to some script to set the state of the delegate + back to its default state. + + \snippet declarative/tutorials/contacts/3_Collections/2/ContactView.qml connection + + Something worth noting at this point is that every delegate created has this connection. + It is important to check whether the delegate is the one in the open state, and + taking some effort to ensure only one is, before acting on the signal from the button. + + \section1 Performance Considerations + + We have now made a contact application that can view a list of contacts, open one, + and close it again. Its now time to take a moment and consider the implications + of a list view delegate. It is created for each and every item in the list, + and while the list cleans up after itself and only has delegate components constructed + for visible items and any single point of animation, the list can scroll very quickly. + This means potentially thousands of delegate components will be constructed and + destroyed when the user is flipping through the list. + + Its important then to try and minimize the complexity of the delegate. This + can be done by delaying the loading of the component. By using the qml property + of the Item component, we can delay building the Contact.qml item until the user + attempts to open the list. + + \snippet declarative/tutorials/contacts/3_Collections/3/ContactView.qml setting qml + + Each item has a qml property that represents the filename for the contents of + a special qmlItem child of the Item. By setting the qml property of the Details + component on clicking the mouse region, the more complex component isn't loaded + until needed. The down side about this though is the properties of Contact + cannot be set until the item is loaded. This requires using the Bind + properties of an item. + + \snippet declarative/tutorials/contacts/3_Collections/3/ContactView.qml binding + + The Bind properties bind a value to another component, however the target of + this binding can be changed, unlike when setting the properties of a component + directly. This means that when the qml property is set, it will change the + qmlItem property of the Details component. This in turn triggers the Bind + elements to set the required properties of the qmlItem, which is now + an instance of the Contact component. +*/ |