API Documentation
Documentation for developing SailfishOS applicationsPageStack QML Type
Stores and manages the pages of an application More...
| Import Statement: | import Sailfish.Silica 1.0 |
Properties
- acceptAnimationRunning : bool
- busy : bool
- currentPage : Item
- depth : int
- pageBackground : component
(preliminary)
Methods
- clear()
- completeAnimation()
- find(object function)
- navigateBack(int operationType)
- navigateForward(int operationType)
- nextPage(Page fromPage)
- pop(var page, int operationType)
- popAttached(var page, int operationType)
- previousPage(Page fromPage)
- push(var page, object properties, int operationType)
- pushAttached(var page, object properties)
- replace(int page, object properties, int operationType)
- replaceAbove(var existingPage, var page, object properties, int operationType)
Detailed Description
The PageStack type provides a stack-based navigation model.
A page stack consists of one or more pages, defined by Page objects. A page may be pushed onto the stack to place it at the top of the stack, or popped to remove it from the stack.
Each Sailfish application, as created by an ApplicationWindow object, contains a single PageStack object (provided by the window's pageStack) containing the content pages that can be displayed by the application. Each page contains the contents to be displayed by the application at any one time. The application window will always show the top-most page in its page stack; thus, pages can be pushed to or popped from the page stack as required to change the top-most page displayed in the application window.
This stack-based navigation model makes it simple to provide hierarchical navigation within an application. When the application is required to provide a page of content, a new page can be pushed onto the stack; if the user requests to return to the previous page, the current page can be popped to reveal the previous page. Otherwise, another page can be pushed onto the stack to navigate deeper into the user interface hierarchy, and so on.
Pages are pushed onto the stack with the push() method, and popped with the pop() method. For example, the application window below displays the page "MyPage.qml":
// main.qml
import Sailfish.Silica 1.0
ApplicationWindow {
initialPage: Qt.resolvedUrl("MyPage.qml")
}Here is MyPage.qml, which defines a page with two buttons. Clicking "Next page" pushes yet another instance of MyPage onto the stack, while clicking "Previous page" pops the currently displayed instance from the stack.
// MyPage.qml
Page {
Column {
width: parent.width
spacing: Theme.paddingLarge
PageHeader { title: "Page " + pageStack.depth }
Button {
text: "Next page"
anchors.horizontalCenter: parent.horizontalCenter
onClicked: pageStack.push(Qt.resolvedUrl("MyPage.qml"))
}
Button {
text: "Previous page"
anchors.horizontalCenter: parent.horizontalCenter
onClicked: pageStack.pop()
}
}
}Page stack navigation
A Sailfish application's page stack supports several user interface gestures and standard buttons that allow the user to easily navigate back and forth between pages.
When the user pushes the current page from left to right, this is interpreted as a "back" navigation gesture, causing the current page to be popped off the stack, and returning the user to the previous page.
As seen in the earlier example on this page, the indicators in the top-left and top-right corners of a page indicate whether the page can be swiped back or forward. Navigation gestures can also be invoked programmatically, via the navigateBack() and navigateForward() functions.
See also Page.
Property Documentation
Reports true if the page stack is currently animating the accept indicator for a dialog page. This occur when a dialog is pushed onto the stack.
Reports true if the page stack is currently transitioning from one page to another. This occurs when a page is in the process of being pushed or popped, which triggers an effect to animate or smoothly transition between pages.
See also push(), pop(), and completeAnimation().
This QML property is under development and is subject to change.
A default background for pages in a PageStack.
In a typical Silica application pages have no backgrounds and the system application background is shown unless a page individually sets its background property. If a pageBackground property is set the background property of Pages will default to that component and only those pages which explicitly clear the background property will show the system application background.
Method Documentation
Removes all pages from the stack.
See also pop().
Completes any running transition animation immediately. The page stack will jump immediately to the final state. Calling this function when an animation is not running has no effect.
Searches for a matching page on the stack and returns it.
This iterates through the page stack from top to bottom and returns the first page encountered for which function(page) is true.
The function parameter should be a JavaScript function object that accepts a page argument and returns true if the page matches, or false otherwise.
Navigates down the stack, equivalent to the action invoked by the user pushing the page from left to right.
The operationType parameter may be one of:
- PageStackAction.Animated
- PageStackAction.Immediate
See also navigateForward().
Navigates up the stack, equivalent to the action invoked by the user pushing the page from right to left.
The operationType parameter may be one of:
- PageStackAction.Animated
- PageStackAction.Immediate
See also navigateBack().
nextPage(Page fromPage) |
Returns the page that follows fromPage in the stack. If fromPage is not specified, the page that follows the current stack top is returned.
See also previousPage().
Removes one or more pages from the stack.
If a page object is specified, all pages above the specified page are removed; otherwise, only the currentPage (that is, the top page on the stack) is removed. If the current page is the only page on the stack, it will not be removed.
The operationType parameter may be one of:
- PageStackAction.Animated
- PageStackAction.Immediate
By default, the page is removed through an animated transition; this animation can be disabled by specifying the operationType parameter as PageStackAction.Immediate.
Returns the page that was previously top of the stack.
See also push(), clear(), and completeAnimation().
Pops one or more attached pages from the top of the stack. If page is specified, then the attached page of the given page is popped from the stack; otherwise, the top page is popped if it is an attached page, or if the top page is not an attached page but it has one that will be popped.
If there are any pages on top of the attached page being popped, or if the target page does not have an attached page, the operation is aborted.
The operationType parameter may be one of:
- PageStackAction.Animated
- PageStackAction.Immediate
If the current stack top is popped as a result of this function, then another page will become the stack top. By default, this change is effected via an animated transition; this animation can be disabled by specifying the operationType parameter as PageStackAction.Immediate.
Returns the page that was previously top of the stack, if the current page is changed. Otherwise returns null.
See also pop() and pushAttached().
previousPage(Page fromPage) |
Returns the page that precedes fromPage in the stack. If fromPage is not specified, the page that precedes the current stack top is returned.
See also nextPage().
Adds the specified page to the top of the stack.
The page parameter may be one of the following:
- An item
- A Component object
- The URL of a Page-type component (for example, "MyPage.qml")
- An array of pages
- The URI of a Sailfish Silica dialog (for example, "Sailfish.Silica.TimePickerDialog")
The operationType parameter may be one of:
- PageStackAction.Animated
- PageStackAction.Immediate
By default, the page is added through an animated transition; this animation can be disabled by specifying the operationType parameter is PageStackAction.Immediate. Additionally, the optional properties parameter specifies a map of properties to be set on the page.
If pages is an array, each value in the array may be an item, Component object or URL as per above. Additionally, an array value may be an object with a 'page' value and an optional 'properties' value, to enable pushing a page with specific properties.
Returns the page instance.
See also pop() and completeAnimation().
Attaches page to the page that is currently top of the stack. The new page is above the current page in stack, but is not shown immediately. The attached page may be shown by navigating forward in the stack. The attached page is not an independent member of the stack; it will be removed from the stack when the page that it is attached to is popped from the stack. A page can only have one attached page. Pushing multiple pages will cause the earlier ones to removed and destroyed.
The page parameter may be one of the following:
- An item
- A Component object
- The URL of a Page-type component (for example, "MyPage.qml")
The optional properties parameter specifies a map of properties to be set on the page.
Returns the attached page instance.
See also push() and popAttached().
Replaces the top page on the stack with page. The page, properties and operationType parameters are the same as those for push().
Returns the new page on the top of the stack.
See also push(), pop(), and replaceAbove().
Replaces one or more pages on the stack with the supplied page.
Any pages above the specified existingPage will be removed. If existingPage is null, all pages on the stack are removed. The page, properties and operationType parameters are the same as those for push().
Returns the new page on the top of the stack.