From 3c18c2a43260a271f8a13e89053eede15d399005 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Tue, 7 Sep 2010 18:34:09 +0200 Subject: Doc: More work on the QML documentation. --- doc/src/declarative/declarativeui.qdoc | 1 + doc/src/declarative/qdeclarativedocument.qdoc | 2 +- doc/src/declarative/qdeclarativemodels.qdoc | 153 ++++++++++++--------- doc/src/declarative/qml-intro.qdoc | 2 +- doc/src/examples/qml-examples.qdoc | 2 +- doc/src/images/qml-listview-snippet.png | Bin 0 -> 2048 bytes doc/src/snippets/declarative/flickable.qml | 50 +++++++ doc/src/snippets/declarative/image.qml | 2 + .../declarative/listview/listview-snippet.qml | 52 +++++++ .../qml-data-models/dynamic-listmodel.qml | 67 +++++++++ .../declarative/qml-data-models/listelements.qml | 77 +++++++++++ .../qml-data-models/listmodel-listview.qml | 64 +++++++++ .../WebKit/qt/declarative/qdeclarativewebview.cpp | 86 ++++++++---- .../graphicsitems/qdeclarativeflickable.cpp | 56 +++++--- .../graphicsitems/qdeclarativeimage.cpp | 2 +- src/declarative/qml/qdeclarativetypeloader.cpp | 2 +- 16 files changed, 502 insertions(+), 116 deletions(-) create mode 100644 doc/src/images/qml-listview-snippet.png create mode 100644 doc/src/snippets/declarative/flickable.qml create mode 100644 doc/src/snippets/declarative/listview/listview-snippet.qml create mode 100644 doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml create mode 100644 doc/src/snippets/declarative/qml-data-models/listelements.qml create mode 100644 doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index ae64e2a..2f43682 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -109,6 +109,7 @@ Module. \list \o \l{Using QML Positioner and Repeater Items} \o \l{QML Data Models} +\o \l{Presenting Data with QML} \o \l{Network Transparency} \endlist diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index 4aed63f..8ca6c11 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -79,7 +79,7 @@ Each instance is created with a different value for its \c text property: \o application.qml \row -\o \snippet doc/src/snippets/declarative/qmldocuments.qml document +\o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document \o \qml import Qt 4.7 diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index ace0465..7548c96 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -41,30 +41,7 @@ delegate may bind to. Here is a ListModel with two roles, \e type and \e age, and a ListView with a delegate that binds to these roles to display their values: -\qml -import Qt 4.7 - -Item { - width: 200; height: 250 - - ListModel { - id: myModel - ListElement { type: "Dog"; age: 8 } - ListElement { type: "Cat"; age: 5 } - } - - Component { - id: myDelegate - Text { text: type + ", " + age } - } - - ListView { - anchors.fill: parent - model: myModel - delegate: myDelegate - } -} -\endqml +\snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document If there is a naming clash between the model's properties and the delegate's properties, the roles can be accessed with the qualified \e model name instead. @@ -91,6 +68,10 @@ QML provides several types of data models among the built-in set of QML elements. In addition, models can be created with C++ and then made available to QML components. +The views used to access data models are described in \l{Presenting Data with QML}. +The use of positioner items to arrange items from a model is covered in +\l{Using QML Positioner and Repeater Items}. + \section1 QML Data Models @@ -99,38 +80,12 @@ made available to QML components. ListModel is a simple hierarchy of elements specified in QML. The available roles are specified by the \l ListElement properties. -\code -ListModel { - id: fruitModel - - ListElement { - name: "Apple" - cost: 2.45 - } - ListElement { - name: "Orange" - cost: 3.25 - } - ListElement { - name: "Banana" - cost: 1.95 - } -} -\endcode +\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model The above model has two roles, \e name and \e cost. These can be bound to by a ListView delegate, for example: -\code -ListView { - width: 200; height: 250 - model: fruitModel - delegate: Row { - Text { text: "Fruit: " + name } - Text { text: "Cost: $" + cost } - } -} -\endcode +\snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view ListModel provides methods to manipulate the ListModel directly via JavaScript. In this case, the first item inserted determines the roles available @@ -138,16 +93,9 @@ to any views that are using the model. For example, if an empty ListModel is created and populated via JavaScript, the roles provided by the first insertion are the only roles that will be shown in the view: -\code -Item { - ListModel { id: fruitModel } - - MouseArea { - anchors.fill: parent - onClicked: fruitModel.append({"cost": 5.95, "name":"Pizza"}) - } -} -\endcode +\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml model +\dots +\snippet doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml mouse area When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name. Even if subsequent roles are added, only the first two will be handled by views @@ -515,3 +463,84 @@ a function in the model, e.g.: updated, and that \e{value} holds the new value. */ + +/*! +\page qml-presenting-data.html +\title Presenting Data with QML + +\section1 Introduction + +Qt Quick contains a set of standard items that can be used to present data in a +number of different ways. For simple user interfaces, +\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used +in combination with +\l{Using QML Positioner and Repeater Items#Positioners}{Positioners} +to obtain pieces of data and arrange them in a user interface. However, when +large quantities of data are involved, it is often better to use models with +the standard views since these contain many built-in display and navigation +features. + +\section1 Views + +Views are scrolling containers for collections of items. They are feature-rich, +supporting many of the use cases found in typical applications, and can be +customized to meet requirements on style and behavior. + +A set of standard views are provided in the basic set of Qt Quick +graphical elements: + +\list +\o \l{#ListView}{ListView} arranges items in a horizontal or vertical list +\o \l{#GridView}{GridView} arranges items in a grid within the available space +\o \l{#PathView}{PathView} arranges items on a path +\endlist + +Unlike these items, \l WebView is not a fully-featured view item, and needs +to be combined with a \l Flickable item to create a view that performs like +a Web browser. + +\section2 ListView + +\l ListView shows a classic list of items with horizontal or vertical placing +of items. + +\beginfloatright +\inlineimage qml-listview-snippet.png +\endfloat + +The following example shows a minimal ListView displaying a sequence of +numbers (using an \l{QML Data Models#An Integer}{integer as a model}). +A simple delegate is used to define an items for each piece of data in the +model. + +\clearfloat +\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document + + + +\section2 GridView + +\l GridView displays items in a grid like an file manager's icon view. + +\section2 PathView + +\l PathView displays items on a path, where the selection remains in +the same place and the items move around it. + +\section1 Decorating Views + +\section2 Headers and Footers + +\section2 Sections + +\section2 Navigation + +In traditional user interfaces, views can be scrolled using standard +controls, such as scroll bars and arrow buttons. In some situations, it +is also possible to drag the view directly by pressing and holding a +mouse button while moving the cursor. In touch-based user interfaces, +this dragging action is often complemented with a flicking action, where +scrolling continues after the user has stopped touching the view. + +\section1 Further Reading +*/ diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc index d735042..b77611c 100644 --- a/doc/src/declarative/qml-intro.qdoc +++ b/doc/src/declarative/qml-intro.qdoc @@ -583,7 +583,7 @@ rectangle. The \c value attribute of 'dial' is set to a value based on the the rotation of the needle image. Notice this piece of code in Dial where the change in \c value modifies the position of the needle. -\snippet examples/declarative/ui-components/dialcontrol/Dial.qml needle angle +\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle angle This is part of the \c needleRotation that rotates the needle and causes the rotation of its shadow. \l SpringAnimation is an element that modifies the value diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc index 8752d14..745baa3 100644 --- a/doc/src/examples/qml-examples.qdoc +++ b/doc/src/examples/qml-examples.qdoc @@ -375,7 +375,7 @@ \title Models and Views: WebView Example \example declarative/modelviews/webview - These examples shows how to use the WebView element. + These examples show how to use the WebView element. \table \row diff --git a/doc/src/images/qml-listview-snippet.png b/doc/src/images/qml-listview-snippet.png new file mode 100644 index 0000000..0ee0ffc Binary files /dev/null and b/doc/src/images/qml-listview-snippet.png differ diff --git a/doc/src/snippets/declarative/flickable.qml b/doc/src/snippets/declarative/flickable.qml new file mode 100644 index 0000000..d7a163b --- /dev/null +++ b/doc/src/snippets/declarative/flickable.qml @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import Qt 4.7 + +Flickable { + width: 200; height: 200 + contentWidth: image.width; contentHeight: image.height + + Image { id: image; source: "bigImage.png" } +} +//! [document] diff --git a/doc/src/snippets/declarative/image.qml b/doc/src/snippets/declarative/image.qml index b0ae032..42efb8f 100644 --- a/doc/src/snippets/declarative/image.qml +++ b/doc/src/snippets/declarative/image.qml @@ -38,8 +38,10 @@ ** ****************************************************************************/ +//! [document] import Qt 4.7 Image { source: "pics/qtlogo.png" } +//! [document] diff --git a/doc/src/snippets/declarative/listview/listview-snippet.qml b/doc/src/snippets/declarative/listview/listview-snippet.qml new file mode 100644 index 0000000..c510472 --- /dev/null +++ b/doc/src/snippets/declarative/listview/listview-snippet.qml @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import Qt 4.7 + +ListView { + width: 50; height: 200 + model: 4 + delegate: Text { + text: index; + font.pixelSize: 40 + } +} +//! [document] diff --git a/doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml b/doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml new file mode 100644 index 0000000..72e27f3 --- /dev/null +++ b/doc/src/snippets/declarative/qml-data-models/dynamic-listmodel.qml @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import Qt 4.7 + +Item { + width: 200; height: 250 + + //! [model] + ListModel { id: fruitModel } + //! [model] + + //! [view] + ListView { + anchors.fill: parent + model: fruitModel + delegate: Row { + Text { text: "Fruit: " + name } + Text { text: "Cost: $" + cost } + } + } + //! [view] + + //! [mouse area] + MouseArea { + anchors.fill: parent + onClicked: fruitModel.append({"cost": 5.95, "name":"Pizza"}) + } + //! [mouse area] +} diff --git a/doc/src/snippets/declarative/qml-data-models/listelements.qml b/doc/src/snippets/declarative/qml-data-models/listelements.qml new file mode 100644 index 0000000..d9cea81 --- /dev/null +++ b/doc/src/snippets/declarative/qml-data-models/listelements.qml @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import Qt 4.7 + +Item { + width: 200; height: 250 + + //! [model] + ListModel { + id: fruitModel + + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } + } + //! [model] + + //! [view] + ListView { + anchors.fill: parent + model: fruitModel + delegate: Row { + Text { text: "Fruit: " + name } + Text { text: "Cost: $" + cost } + } + } + //! [view] +} +//! [document] diff --git a/doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml b/doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml new file mode 100644 index 0000000..92107f1 --- /dev/null +++ b/doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import Qt 4.7 + +Item { + width: 200; height: 250 + + ListModel { + id: myModel + ListElement { type: "Dog"; age: 8 } + ListElement { type: "Cat"; age: 5 } + } + + Component { + id: myDelegate + Text { text: type + ", " + age } + } + + ListView { + anchors.fill: parent + model: myModel + delegate: myDelegate + } +} +//! [document] diff --git a/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp b/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp index 1538133..67ce708 100644 --- a/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp +++ b/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp @@ -141,46 +141,76 @@ void GraphicsWebView::mouseMoveEvent(QGraphicsSceneMouseEvent* event) \qmlclass WebView QDeclarativeWebView \ingroup qml-view-elements \since 4.7 - \brief The WebView item allows you to add web content to a canvas. + \brief The WebView item allows you to add Web content to a canvas. \inherits Item - A WebView renders web content based on a URL. + A WebView renders Web content based on a URL. This type is made available by importing the \c QtWebKit module: \bold{import QtWebKit 1.0} - If the width and height of the item is not set, they will - dynamically adjust to a size appropriate for the content. - This width may be large for typical online web pages. + The WebView item includes no scrolling, scaling, toolbars, or other common browser + components. These must be implemented around WebView. See the \l{QML Web Browser} + example for a demonstration of this. - If the width or height is explictly set, the rendered website - will be clipped, not scaled, to fit into the set dimensions. + The page to be displayed by the item is specified using the \l url property, + and this can be changed to fetch and display a new page. While the page loads, + the \l progress property is updated to indicate how much of the page has been + loaded. - If the preferredWidth is set, the width will be this amount or larger, - usually laying out the web content to fit the preferredWidth. + \section1 Appearance - \qml - import QtWebKit 1.0 + If the width and height of the item is not set, they will dynamically adjust + to a size appropriate for the content. This width may be large for typical + online web pages, typically greater than 800 by 600 pixels. - WebView { - url: "http://www.nokia.com" - preferredWidth: 490 - preferredHeight: 400 - scale: 0.5 - smooth: false - smoothCache: true - } - \endqml + If the \l{Item::}{width} or \l{Item::}{height} is explictly set, the rendered Web site will be + clipped, not scaled, to fit into the set dimensions. - \image webview.png + If the preferredWidth property is set, the width will be this amount or larger, + usually laying out the Web content to fit the preferredWidth. - The item includes no scrolling, scaling, - toolbars, etc., those must be implemented around WebView. See the WebBrowser example - for a demonstration of this. + The appearance of the content can be controlled to a certain extent by changing + the settings.standardFontFamily property and other settings related to fonts. + + The page can be zoomed by calling the heuristicZoom() method, which performs a + series of tests to determine whether zoomed content will be displayed in an + appropriate way in the space allocated to the item. + + \section1 User Interaction and Navigation + + By default, certain mouse and touch events are delivered to other items in + preference to the Web content. For example, when a scrolling view is created + by placing a WebView in a Flickable, move events are delivered to the Flickable + so that the user can scroll the page. This prevents the user from accidentally + selecting text in a Web page instead of scrolling. + + The pressGrabTime property defines the time the user must touch or press a + mouse button over the WebView before the Web content will receive the move + events it needs to select text and images. + + When this item has keyboard focus, all keyboard input will be sent directly to + the Web page within. + + When the navigates by clicking on links, the item records the pages visited + in its internal history + + Because this item is designed to be used as a component in a browser, it + exposes \l{Action}{actions} for \l back, \l forward, \l reload and \l stop. + These can be triggered to change the current page displayed by the item. + + \section1 Example Usage + + \beginfloatright + \inlineimage webview.png + \endfloat + + The following example displays a scaled down Web page at a fixed size. + + \snippet doc/src/snippets/declarative/webview/webview.qml document - When this item has keyboard focus, all keyboard input will be sent directly to the - web page within. + \clearfloat \sa {declarative/modelviews/webview}{WebView example}, {demos/declarative/webbrowser}{Web Browser demo} */ @@ -555,11 +585,11 @@ bool QDeclarativeWebView::heuristicZoom(int clickX, int clickY, qreal maxZoom) \qmlproperty int WebView::pressGrabTime The number of milliseconds the user must press before the WebView - starts passing move events through to the web engine (rather than + starts passing move events through to the Web engine (rather than letting other QML elements such as a Flickable take them). Defaults to 400ms. Set to 0 to always grab and pass move events to - the web engine. + the Web engine. */ int QDeclarativeWebView::pressGrabTime() const { diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp index b302393..062bbfb 100644 --- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp @@ -350,24 +350,34 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd() \brief The Flickable item provides a surface that can be "flicked". \inherits Item - Flickable places its children on a surface that can be dragged and flicked. + The Flickable item places its children on a surface that can be dragged + and flicked, causing the view onto the child items to scroll. This + behavior forms the basis of Items that are designed to show large numbers + of child items, such as \l ListView and \l GridView. - \code - import Qt 4.7 + In traditional user interfaces, views can be scrolled using standard + controls, such as scroll bars and arrow buttons. In some situations, it + is also possible to drag the view directly by pressing and holding a + mouse button while moving the cursor. In touch-based user interfaces, + this dragging action is often complemented with a flicking action, where + scrolling continues after the user has stopped touching the view. - Flickable { - width: 200; height: 200 - contentWidth: image.width; contentHeight: image.height + Flickable does not automatically clip its contents. If it is not used as + a full-screen item, you should consider setting the \l{Item::}{clip} property + to true. - Image { id: image; source: "bigImage.png" } - } - \endcode + \section1 Example Usage + + \beginfloatright + \inlineimage flickable.gif + \endfloat - \image flickable.gif + The following example shows a large - Flickable does not automatically clip its contents. If - it is not full-screen it is likely that \l {Item::clip}{clip} should be set - to \c true. + \clearfloat + \snippet doc/src/snippets/declarative/flickable.qml document + + \section1 Limitations \note Due to an implementation detail, items placed inside a Flickable cannot anchor to it by \c id. Use \c parent instead. @@ -491,12 +501,15 @@ void QDeclarativeFlickable::setContentY(qreal pos) /*! \qmlproperty bool Flickable::interactive - This property holds whether the user can interact with the Flickable. A user - cannot drag or flick a Flickable that is not interactive. + This property describes whether the user can interact with the Flickable. + A user cannot drag or flick a Flickable that is not interactive. + + By default, this property is true. This property is useful for temporarily disabling flicking. This allows - special interaction with Flickable's children: for example, you might want to - freeze a flickable map while scrolling through a pop-up dialog that is a child of the Flickable. + special interaction with Flickable's children; for example, you might want + to freeze a flickable map while scrolling through a pop-up dialog that + is a child of the Flickable. */ bool QDeclarativeFlickable::isInteractive() const { @@ -1333,8 +1346,8 @@ bool QDeclarativeFlickable::isFlicking() const \qmlproperty bool Flickable::flickingHorizontally \qmlproperty bool Flickable::flickingVertically - These properties hold whether the view is currently moving horizontally - or vertically due to the user flicking the view. + These properties describe whether the view is currently moving horizontally, + vertically or in either direction, due to the user flicking the view. */ bool QDeclarativeFlickable::isFlickingHorizontally() const { @@ -1386,8 +1399,9 @@ bool QDeclarativeFlickable::isMoving() const \qmlproperty bool Flickable::movingHorizontally \qmlproperty bool Flickable::movingVertically - These properties hold whether the view is currently moving horizontally - or vertically due to the user either dragging or flicking the view. + These properties describe whether the view is currently moving horizontally, + vertically or in either direction, due to the user either dragging or + flicking the view. */ bool QDeclarativeFlickable::isMovingHorizontally() const { diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp index 2fab373..9cd9ad6 100644 --- a/src/declarative/graphicsitems/qdeclarativeimage.cpp +++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp @@ -73,7 +73,7 @@ QT_BEGIN_NAMESPACE The following example shows the simplest usage of the Image element. - \snippet doc/src/snippets/declarative/image.qml + \snippet doc/src/snippets/declarative/image.qml document \beginfloatleft \image declarative-qtlogo.png diff --git a/src/declarative/qml/qdeclarativetypeloader.cpp b/src/declarative/qml/qdeclarativetypeloader.cpp index ed41314..9b42065 100644 --- a/src/declarative/qml/qdeclarativetypeloader.cpp +++ b/src/declarative/qml/qdeclarativetypeloader.cpp @@ -224,7 +224,7 @@ void QDeclarativeDataBlob::setError(const QDeclarativeError &errors) } /*! -\override +\overload */ void QDeclarativeDataBlob::setError(const QList &errors) { -- cgit v0.12