diff options
| -rw-r--r-- | doc/src/declarative/dynamicobjects.qdoc | 48 | ||||
| -rw-r--r-- | doc/src/snippets/declarative/dynamicObjects.qml | 30 | ||||
| -rw-r--r-- | doc/src/snippets/declarative/flickableScrollbar.qml | 26 | ||||
| -rw-r--r-- | src/declarative/graphicsitems/qdeclarativeflickable.cpp | 50 |
4 files changed, 102 insertions, 52 deletions
diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index 5cdd768..dc0277d 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -132,36 +132,24 @@ do not have an id in QML. \section1 Deleting Objects Dynamically -You should generally avoid dynamically deleting objects that you did not -dynamically create. In many UIs, it is sufficient to set the opacity to 0 or -to move the item off of the edge of the screen. If you have lots of dynamically -created items however, deleting them when they are no longer used will provide -a worthwhile performance benefit. Note that you should never manually delete -items which were dynamically created by QML Elements such as \l{Loader}. - -To manually delete a QML item, call its destroy method. This method has one -argument, which is an approximate delay in milliseconds and which defaults to zero. This -allows you to wait until the completion of an animation or transition. An example: - -\code - Component { - id: fadesOut - Rectangle{ - id: rect - width: 40; height: 40; - NumberAnimation on opacity { from:1; to:0; duration: 1000 } - Component.onCompleted: rect.destroy(1000); - } - } - function createFadesOut(parentItem) - { - var object = fadesOut.createObject(); - object.parent = parentItem; - } -\endcode - -In the above example, the dynamically created rectangle calls destroy as soon as it is created, - but delays long enough for its fade out animation to be played. +In many user interfaces, it is sufficient to set an item's opacity to 0 or +to move the item off the screen instead of deleting the item. If you have +lots of dynamically created items, however, you may receive a worthwhile +performance benefit if unused items are deleted. + +Note that you should never manually delete items that were dynamically created +by QML elements (such as \l Loader). Also, you should generally avoid deleting +items that you did not dynamically create yourself. + +Items can be deleted using the \c destroy() method. This method has an optional +argument (which defaults to 0) that specifies the approximate delay in milliseconds +before the object is to be destroyed. This allows you to wait until the completion of +an animation or transition. An example: + +\snippet doc/src/snippets/declarative/dynamicObjects.qml 0 + +Here, \c Rectangle objects are destroyed one second after they are created, which is long +enough for the \c NumberAnimation to be played before the object is destroyed. */ diff --git a/doc/src/snippets/declarative/dynamicObjects.qml b/doc/src/snippets/declarative/dynamicObjects.qml new file mode 100644 index 0000000..dd55d78 --- /dev/null +++ b/doc/src/snippets/declarative/dynamicObjects.qml @@ -0,0 +1,30 @@ +import Qt 4.7 + +//![0] +Rectangle { + id: rootItem + width: 300 + height: 300 + + Component { + id: rectComponent + + Rectangle { + id: rect + width: 40; height: 40; + color: "red" + + NumberAnimation on opacity { from: 1; to: 0; duration: 1000 } + + Component.onCompleted: rect.destroy(1000); + } + } + + function createRectangle() { + var object = rectComponent.createObject(); + object.parent = rootItem; + } + + Component.onCompleted: createRectangle() +} +//![0] diff --git a/doc/src/snippets/declarative/flickableScrollbar.qml b/doc/src/snippets/declarative/flickableScrollbar.qml new file mode 100644 index 0000000..147751a --- /dev/null +++ b/doc/src/snippets/declarative/flickableScrollbar.qml @@ -0,0 +1,26 @@ +import Qt 4.7 + +//![0] +Rectangle { + width: 200; height: 200 + + Flickable { + id: flickable +//![0] + anchors.fill: parent + contentWidth: image.width; contentHeight: image.height + + Image { id: image; source: "pics/qt.png" } +//![1] + } + + Rectangle { + id: scrollbar + anchors.right: flickable.right + y: flickable.visibleArea.yPosition * flickable.height + width: 10 + height: flickable.visibleArea.heightRatio * flickable.height + color: "black" + } +} +//![1] diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp index b713987..62a08ad 100644 --- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp @@ -345,19 +345,21 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd() \code Flickable { - width: 200; height: 200; contentWidth: image.width; contentHeight: image.height - Image { id: image; source: "bigimage.png" } + width: 200; height: 200 + contentWidth: image.width; contentHeight: image.height + + Image { id: image; source: "bigImage.png" } } \endcode \image flickable.gif - \note Flickable does not automatically clip its contents. If - it is not full-screen it is likely that \c clip should be set - to true. + 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. - \note Due to an implementation detail items placed inside a flickable cannot anchor to it by - id, use 'parent' instead. + \note Due to an implementation detail, items placed inside a Flickable cannot anchor to it by + \c id. Use \c parent instead. */ /*! @@ -400,18 +402,17 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd() These properties describe the position and size of the currently viewed area. The size is defined as the percentage of the full view currently visible, scaled to 0.0 - 1.0. The page position is usually in the range 0.0 (beginning) to - 1.0 minus size ratio (end), i.e. yPosition is in the range 0.0 to 1.0-heightRatio. + 1.0 minus size ratio (end), i.e. \c yPosition is in the range 0.0 to 1.0-\c heightRatio. However, it is possible for the contents to be dragged outside of the normal range, resulting in the page positions also being outside the normal range. - These properties are typically used to draw a scrollbar, for example: - \code - Rectangle { - opacity: 0.5; anchors.right: MyListView.right-2; width: 6 - y: MyListView.visibleArea.yPosition * MyListView.height - height: MyListView.visibleArea.heightRatio * MyListView.height - } - \endcode + These properties are typically used to draw a scrollbar. For example: + + \snippet doc/src/snippets/declarative/flickableScrollbar.qml 0 + \dots 4 + \snippet doc/src/snippets/declarative/flickableScrollbar.qml 1 + + \sa {declarative/scrollbar}{scrollbar example} */ QDeclarativeFlickable::QDeclarativeFlickable(QDeclarativeItem *parent) @@ -479,11 +480,12 @@ void QDeclarativeFlickable::setContentY(qreal pos) /*! \qmlproperty bool Flickable::interactive - A user cannot drag or flick a Flickable that is not 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 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 viewing detailed information on a location popup that is a child of the Flickable. + freeze a flickable map while scrolling through a pop-up dialog that is a child of the Flickable. */ bool QDeclarativeFlickable::isInteractive() const { @@ -1026,7 +1028,7 @@ void QDeclarativeFlickable::setOverShoot(bool o) This enables the feeling that the edges of the view are soft, rather than a hard physical boundary. - boundsBehavior can be one of: + The \c boundsBehavior can be one of: \list \o \e StopAtBounds - the contents can not be dragged beyond the boundary @@ -1059,12 +1061,16 @@ void QDeclarativeFlickable::setBoundsBehavior(BoundsBehavior b) \qmlproperty int Flickable::contentHeight The dimensions of the content (the surface controlled by Flickable). Typically this - should be set to the combined size of the items placed in the Flickable. + should be set to the combined size of the items placed in the Flickable. Note this + can be set automatically using \l {Item::childrenRect.width}{childrenRect.width} + and \l {Item::childrenRect.height}{childrenRect.height}. For example: \code Flickable { - width: 320; height: 480; contentWidth: image.width; contentHeight: image.height - Image { id: image; source: "bigimage.png" } + width: 320; height: 480 + contentWidth: childrenRect.width; contentHeight: childrenRect.height + + Image { id: image; source: "bigImage.png" } } \endcode */ |