From 0a4b78de06b60a5fc0a9182687ded099968c4055 Mon Sep 17 00:00:00 2001 From: Martin Jones Date: Thu, 30 Apr 2009 13:19:10 +1000 Subject: Documentation for ListView Convert to new format, use \snippet. --- doc/src/declarative/pics/ListViewHorizontal.png | Bin 2519 -> 5802 bytes doc/src/declarative/pics/ListViewSections.png | Bin 0 -> 7596 bytes doc/src/declarative/pics/trivialListView.png | Bin 2387 -> 6160 bytes .../listview/dummydata/ContactModel.qml | 18 +++ .../snippets/declarative/listview/highlight.qml | 59 +++++++++ doc/src/snippets/declarative/listview/listview.qml | 55 ++++++++ .../declarative/listview/dummydata/MyPetsModel.qml | 47 ++++--- examples/declarative/listview/sections.qml | 69 ++++++++++ src/declarative/fx/qfxlistview.cpp | 143 +++++++-------------- src/declarative/util/qmlstateoperations.cpp | 1 + 10 files changed, 275 insertions(+), 117 deletions(-) create mode 100644 doc/src/declarative/pics/ListViewSections.png create mode 100644 doc/src/snippets/declarative/listview/dummydata/ContactModel.qml create mode 100644 doc/src/snippets/declarative/listview/highlight.qml create mode 100644 doc/src/snippets/declarative/listview/listview.qml create mode 100644 examples/declarative/listview/sections.qml diff --git a/doc/src/declarative/pics/ListViewHorizontal.png b/doc/src/declarative/pics/ListViewHorizontal.png index 63c7c86..4633a0e 100644 Binary files a/doc/src/declarative/pics/ListViewHorizontal.png and b/doc/src/declarative/pics/ListViewHorizontal.png differ diff --git a/doc/src/declarative/pics/ListViewSections.png b/doc/src/declarative/pics/ListViewSections.png new file mode 100644 index 0000000..9270126 Binary files /dev/null and b/doc/src/declarative/pics/ListViewSections.png differ diff --git a/doc/src/declarative/pics/trivialListView.png b/doc/src/declarative/pics/trivialListView.png index 175e455..3782570 100644 Binary files a/doc/src/declarative/pics/trivialListView.png and b/doc/src/declarative/pics/trivialListView.png differ diff --git a/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml new file mode 100644 index 0000000..302dfd2 --- /dev/null +++ b/doc/src/snippets/declarative/listview/dummydata/ContactModel.qml @@ -0,0 +1,18 @@ + + + + Bill Smith + 555 3264 + + + John Brown + 555 8426 + + + Sam Wise + 555 0473 + + diff --git a/doc/src/snippets/declarative/listview/highlight.qml b/doc/src/snippets/declarative/listview/highlight.qml new file mode 100644 index 0000000..d8bbb22 --- /dev/null +++ b/doc/src/snippets/declarative/listview/highlight.qml @@ -0,0 +1,59 @@ +Rect { + width: 180 + height: 200 + color: "white" + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: Delegate + Item { + id: Wrapper + width: 180 + height: 40 + VerticalLayout { + x: 5; y: 5 + Text { + text: 'Name: ' + name + } + Text { + text: 'Number: ' + number + } + } + } + } +//! [0] + // Specify a highlight with custom movement. Note that autoHighlight + // is set to false in the ListView so that we can control how the + // highlight moves to the current item. +//! [1] + Component { + id: Highlight + Rect { + width: 180 + height: 40 + color: "lightsteelblue" + radius: 5 + y: Follow { + source: List.current.y + spring: 3 + damping: 0.1 + } + } + } + ListView { + id: List + width: 180 + height: parent.height + model: ContactModel + delegate: Delegate + highlight: Highlight + autoHighlight: false + focus: true + } +//! [1] +} diff --git a/doc/src/snippets/declarative/listview/listview.qml b/doc/src/snippets/declarative/listview/listview.qml new file mode 100644 index 0000000..5b99bbd --- /dev/null +++ b/doc/src/snippets/declarative/listview/listview.qml @@ -0,0 +1,55 @@ +//! [3] +Rect { + width: 480 + height: 40 + color: "white" + // ContactModel model is defined in dummydata/ContactModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + + // Define a delegate component. A component will be + // instantiated for each visible item in the list. +//! [0] + Component { + id: Delegate + Item { + id: Wrapper + width: 180 + height: 40 + VerticalLayout { + x: 5; y: 5 + Text { + text: 'Name: ' + name + } + Text { + text: 'Number: ' + number + } + } + } + } +//! [0] + // Define a highlight component. Just one of these will be instantiated + // by each ListView and placed behind the current item. +//! [1] + Component { + id: Highlight + Rect { + color: "lightsteelblue" + radius: 5 + } + } +//! [1] + // The actual list +//! [2] + ListView { + width: 480 + height: parent.height + model: ContactModel + delegate: Delegate + highlight: Highlight + focus: true + orientation: 'Horizontal' + } +//! [2] +} +//! [3] diff --git a/examples/declarative/listview/dummydata/MyPetsModel.qml b/examples/declarative/listview/dummydata/MyPetsModel.qml index 5af7fbf..e1617a3 100644 --- a/examples/declarative/listview/dummydata/MyPetsModel.qml +++ b/examples/declarative/listview/dummydata/MyPetsModel.qml @@ -4,48 +4,57 @@ Be sure to name the file the same as the id. --> - Rover - Dog - 5 + Polly + Parrot + 12 + Small - Whiskers - Cat - 2 + Penny + Turtle + 4 + Small Warren Rabbit 2 - - - Polly - Parrot - 12 + Small Spot Dog 9 + Medium - Tiny - Elephant - 15 - - - Penny - Turtle - 4 + Whiskers + Cat + 2 + Medium Joey Kangaroo 1 + Medium Kimba Bunny 65 + Large + + + Rover + Dog + 5 + Large + + + Tiny + Elephant + 15 + Large diff --git a/examples/declarative/listview/sections.qml b/examples/declarative/listview/sections.qml new file mode 100644 index 0000000..60acd62 --- /dev/null +++ b/examples/declarative/listview/sections.qml @@ -0,0 +1,69 @@ +//! [0] +Rect { + width: 200 + height: 240 + color: "white" + // MyPets model is defined in dummydata/MyPetsModel.qml + // The viewer automatically loads files in dummydata/* to assist + // development without a real data source. + // This one contains my pets. + + // Define a delegate component that includes a separator for sections. + Component { + id: PetDelegate + Item { + id: Wrapper + width: 200 + // My height is the combined height of the description and the section separator + height: Separator.height + Desc.height + Rect { + id: Separator + color: "lightsteelblue" + width: parent.width + // Only show the section separator when we are the beginning of a new section + // Note that for this to work nicely, the list must be ordered by section. + height: Wrapper.ListView.prevSection != Wrapper.ListView.section ? 20 : 0 + opacity: Wrapper.ListView.prevSection != Wrapper.ListView.section ? 1 : 0 + Text { + text: Wrapper.ListView.section; font.bold: true + x: 2; height: parent.height; vAlign: 'AlignVCenter' + } + } + Item { + id: Desc + x: 5 + height: Layout.height + 4 + anchors.top: Separator.bottom + VerticalLayout { + id: Layout + y: 2 + Text { text: 'Name: ' + name } + Text { text: 'Type: ' + type } + Text { text: 'Age: ' + age } + } + } + } + } + // Define a highlight component. Just one of these will be instantiated + // by each ListView and placed behind the current item. + Component { + id: PetHighlight + Rect { + color: "#FFFF88" + } + } + // The list + ListView { + id: List + width: 200 + height: parent.height + model: MyPetsModel + delegate: PetDelegate + highlight: PetHighlight + // The sectionExpression is simply the size of the pet. + // We use this to determine which section we are in above. + sectionExpression: "size" + focus: true + } +} +//! [0] diff --git a/src/declarative/fx/qfxlistview.cpp b/src/declarative/fx/qfxlistview.cpp index 0724e3a..13e5b21 100644 --- a/src/declarative/fx/qfxlistview.cpp +++ b/src/declarative/fx/qfxlistview.cpp @@ -798,37 +798,23 @@ void QFxListViewPrivate::fixupX() \brief The ListView element provides a list view of items provided by a model. The model is typically provided by a QAbstractListModel "C++ model object", but can also be created directly in XML. - The items are laid out vertically or horizontally and may be flicked to scroll. The below example creates a very simple vertical list, using an XML model. \image trivialListView.png - \code - - - - John - Smith - - - Bill - Jones - - - Jane - Doe - - - - - - - - - - - \endcode + + The user interface defines a delegate to display an item, a highlight, + and the ListView which uses the above. + + \snippet doc/src/snippets/declarative/listview/listview.qml 3 + + The model is defined as a ListModel using XML: + \quotefromfile doc/src/snippets/declarative/listview/dummydata/ContactModel.qml + \skipto - - John - Smith - - - Bill - Jones - - - Jane - Doe - - - - - \endcode + Models can also be created directly in XML, using the \l ListModel element. */ QVariant QFxListView::model() const { @@ -922,17 +890,7 @@ void QFxListView::setModel(const QVariant &model) The delegate provides a template describing what each item in the view should look and act like. Here is an example delegate: - \code - - - - - - - ... - - \endcode + \snippet doc/src/snippets/declarative/listview/listview.qml 0 */ QmlComponent *QFxListView::delegate() const { @@ -1012,13 +970,9 @@ int QFxListView::count() const The below example demonstrates how to make a simple highlight for a vertical list. - \code - - - - - \endcode - \image ListViewHighlight.png + + \snippet doc/src/snippets/declarative/listview/listview.qml 1 + \image trivialListView.png \sa autoHighlight */ @@ -1043,17 +997,12 @@ void QFxListView::setHighlight(QmlComponent *highlight) If autoHighlight is true, the highlight will be moved smoothly to follow the current item. If autoHighlight is false, the highlight will not be moved by the view, and must be implemented - by the highlight, for example: - - \code - - - - - - - - \endcode + by the highlight. The following example creates a highlight with + its motion defined by the spring \l {Follow}: + + \snippet doc/src/snippets/declarative/listview/highlight.qml 1 + + \sa highlight */ bool QFxListView::autoHighlight() const { @@ -1079,11 +1028,18 @@ void QFxListView::setAutoHighlight(bool autoHighlight) The modes supported are: \list \i Free - For Mouse, the current item may be positioned anywhere, - whether within the visible area, or outside. during Keyboard interaction, + whether within the visible area, or outside. During Keyboard interaction, the current item can move within the visible area, and the view will scroll to keep the highlight visible. - \i Snap - - \i SnapAuto - + \i Snap - For mouse, the current item may be positioned anywhere, + whether within the visible area, or outside. During keyboard interaction, + the current item will be kept in the visible area and will prefer to be + positioned at the \l snapPosition, however the view will never scroll + beyond the beginning or end of the view. + \i SnapAuto - For both mouse and keyboard, the current item will be + kept at the \l {snapPosition}. Additionally, if the view is dragged or + flicked, the current item will be automatically updated to be the item + currently at the snapPosition. \endlist */ QFxListView::CurrentItemPositioning QFxListView::currentItemPositioning() const @@ -1121,10 +1077,10 @@ void QFxListView::setSnapPosition(int pos) \qmlproperty enumeration ListView::orientation This property holds the orientation of the list. - Possible values are \c Qt::Vertical (default) and \c Qt::Horizontal. + Possible values are \c Vertical (default) and \c Horizontal. Vertical Example: - \image ListViewVertical.png + \image trivialListView.png Horizontal Example: \image ListViewHorizontal.png */ @@ -1205,24 +1161,15 @@ void QFxListView::setCacheBuffer(int b) \qmlproperty string ListView::sectionExpression This property holds the expression to be evaluated for the section attached property. - Each item in the list has attached properties named \c section and - \c prevSection. These may be used to place a section header for - related items. The example below assumes that the model is alphabetically - sorted. The section expression is the first character of the \c description - property. If \c section and \c prevSection differ, the item will - display a section header. - - \code - - - - - - - - - - \endcode + Each item in the list has attached properties named \c ListView.section and + \c ListView.prevSection. These may be used to place a section header for + related items. The example below assumes that the model is sorted by size of + pet. The section expression is the size property. If \c ListView.section and + \c ListView.prevSection differ, the item will display a section header. + + \snippet examples/declarative/listview/sections.qml 0 + + \image ListViewSections.png */ QString QFxListView::sectionExpression() const { diff --git a/src/declarative/util/qmlstateoperations.cpp b/src/declarative/util/qmlstateoperations.cpp index 8a10ca3..755befe 100644 --- a/src/declarative/util/qmlstateoperations.cpp +++ b/src/declarative/util/qmlstateoperations.cpp @@ -59,6 +59,7 @@ public: }; /*! + \preliminary \qmlclass ParentChange \brief The ParentChange element allows you to reparent an object in a state. */ -- cgit v0.12