PullToRefresh
Pull-to-refresh component for Flickables to reload a model upon pull. More...
Import Statement: | import Ubuntu.Components 1.1 |
Since: | Ubuntu.Components 1.1 |
Inherits: |
Properties
- activeFocusOnPress : bool
- content : Component
- offset : real
- refreshing : bool
- releaseToRefresh : bool
- style : Component
- target : Flickable
Signals
- refresh()
Detailed Description
The component provides ability to initiate data model refresh by pulling the attached Flickable's content. The refresh can be initiated when the flickable content is at its top boundary. By dragging the content further, reaching the threshold value defined by the style will initiate the manual refresh by emitting the refresh signal. The progress of the refresh must be notified to the component by defining the completion clause to the refreshing property.
import QtQuick 2.2 import QtQuick.XmlListModel 2.0 import Ubuntu.Components 1.1 import Ubuntu.Components.ListItems 1.0 MainView { width: units.gu(40) height: units.gu(71) XmlListModel { id: listModel source: "http://feeds.reuters.com/reuters/topNews" query: "/rss/channel/item" XmlRole { name: "title"; query: "title/string()" } } Page { title: "Reuters" ListView { id: view anchors.fill: parent model: listModel delegate: Standard { width: ListView.view.width height: units.gu(5) text: title } PullToRefresh { refreshing: view.model.status === XmlListModel.Loading onRefresh: view.model.reload() } } } }
Note: UbuntuListView has a built-in PullToRefresh, therefore it is recommended to use UbuntuListView instead of ListView.
The component will also show the progress of the model's update when the refresh gets initiated by the model or from other party. Style implementations can decide whether to visualize that or not.
As default, the component displays a Label visualizing the two states of the component, which is pull to refresh and release to refresh. As mentioned, this is driven by the threshold value specified by the style, and the state is reported by the releaseToRefresh property. The content specifies the visuals to be shown by the component. Custom implementations can hold any component, which will be anchor filled to the component itself.
import QtQuick 2.2 import QtQuick.XmlListModel 2.0 import Ubuntu.Components 1.1 import Ubuntu.Components.ListItems 1.0 MainView { width: units.gu(40) height: units.gu(71) XmlListModel { id: listModel source: "http://feeds.reuters.com/reuters/topNews" query: "/rss/channel/item" XmlRole { name: "title"; query: "title/string()" } } Page { title: "Reuters" ListView { id: view anchors.fill: parent model: listModel delegate: Standard { width: ListView.view.width height: units.gu(5) text: title } PullToRefresh { id: pullToRefresh refreshing: view.model.status === XmlListModel.Loading onRefresh: view.model.reload() content: Item { Icon { name: pullToRefresh.releaseToRefresh ? "search" : "" height: parent.height width: height anchors.horizontalCenter: parent.horizontalCenter } } } } } }
Note: When declared as child of Flickable, set parent to the flickable explicitly so the component does not land in the content of Flickable.
import QtQuick 2.2 import QtQuick.XmlListModel 2.0 import Ubuntu.Components 1.1 import Ubuntu.Components.ListItems 1.0 MainView { id: main width: units.gu(40) height: units.gu(71) XmlListModel { id: rssFeed source: "http://feeds.reuters.com/reuters/topNews" query: "/rss/channel/item" XmlRole { name: "title"; query: "title/string()" } } Page { title: "Reuters" Flickable { id: flickable anchors.fill: parent contentHeight: column.childrenRect.height contentWidth: column.childrenRect.width Column { id: column Repeater { model: rssFeed Standard { width: main.width height: units.gu(5) text: title } } } PullToRefresh { parent: flickable refreshing: rssFeed.status === XmlListModel.Loading onRefresh: rssFeed.reload() } } } }
Styling
The component style API is defined by the PullToRefreshStyle component. Styles may define different ways to initiate refresh upon dragging.
Property Documentation
activeFocusOnPress : bool |
The property specifies whether the StyledItem can gain focus on a mouse press/touch or not. When the value is true, the focus will be set on the component when the mouse is pressed over it or touched. However if one of the component's ancestor StyledItem or derived is having the property value false, the focus will not be gained automatically.
In the following example the TextField will stay focused when clicked on the red rectangle.
import QtQuick 2.2 import Ubuntu.Components 1.1 Column { width: units.gu(50) height: units.gu(100) StyledItem { objectName: "passiveScope" width: parent.width height: units.gu(30) Rectangle { anchors.fill: parent color: "red" StyledItem { objectName: "activeScope" activeFocusOnPress: true anchors.fill: parent } } } TextField { id: input text: "The input stays focus even if red box is clicked" } Component.onCompleted: input.forceActiveFocus() Connections { target: window onActiveFocusItemChanged: console.debug("focus on", window.activeFocusItem) } }
The default value is false.
This QML property was introduced in Ubuntu.Components 1.1.
content : Component |
The property holds the visuals to be displayed when the component is revealed upon manual refresh. The default value is a Label showing "Pull to refresh..." text when the component is pulled down till the activation threshold, and "Release to refresh..." after that.
read-onlyoffset : real |
The property holds the offset the component is pulled from the target Flickable's topMargin. The property can be used to provide animations in custom contents.
refreshing : bool |
The property notifies the component about the ongoing refresh operation.
read-onlyreleaseToRefresh : bool |
The property specifies when the component is ready to trigger the refresh() signal. The logic is defined by the style and the value is transferred from the style's releaseToRefresh property. The property can be used to define custom visuals for content.
style : Component |
Component instantiated immediately and placed below everything else.
target : Flickable |
The Flickable or derivate the component is attached to. This can only be the parent or a sibling of the component. Defaults to the parent.