API Documentation

Documentation for developing SailfishOS applications

PageStack QML Type

Stores and manages the pages of an application More...

Import Statement: import Sailfish.Silica 1.0

Properties

Methods

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

acceptAnimationRunning : bool

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.


busy : bool

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().


currentPage : Item

Reports the page at the top of the stack.


depth : int

Reports the number of pages in the stack.


Method Documentation

clear()

Removes all pages from the stack.

See also pop().


completeAnimation()

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.


find(object function)

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().


pop(var page, int operationType)

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().


popAttached(var page, int operationType)

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().


push(var page, object properties, int operationType)

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().


pushAttached(var page, object properties)

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().


replace(int page, object properties, int operationType)

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().


replaceAbove(var existingPage, var page, object properties, int operationType)

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.

See also push() and pop().


We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.