API Documentation

Documentation for developing SailfishOS applications

Page QML Type

A single page within an application More...

Import Statement: import Sailfish.Silica 1.0
Inherited By:

ColorPickerPage, DatePickerDialog, Dialog, and TimePickerDialog


Detailed Description

The Page type provides a container for the contents of a single page within an application.

A page contains the screen contents that are displayed within an ApplicationWindow at any one time. Applications have one or more pages: each page defines an individual screen of content to which the user may navigate from within the application window. For example, a simple game may have one page containing the game play interface, a second page that displays high scores, and a third page with game rules and instructions. Any application can change the page currently displayed within its window by adding or removing pages from the application page stack.

The Page type is simply a container for the contents of a page. Its width and height properties are automatically sized to the full width and height of the screen for the current orientation. Do not use the anchors property on the page, or it will not resize correctly. For convenience, you can use the PageHeader type to display the page title.

Note that pages may be resized due to orientation changes or the input panel being displayed. It is common to place content in a SilicaFlickable to ensure that it can be scrolled if the page becomes too small to display all of the content.

Below is a page that displays a simple list:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Page {
     SilicaFlickable {
         anchors.fill: parent
         contentHeight: column.height
         Column {
             id: column
             width: parent.width
             spacing: 20

             PageHeader { title: "List of items" }
             Label { text: "Item 1" }
             Label { text: "Item 2" }
             Label { text: "Item 3" }

Enabling orientation changes

By default, pages only support the portrait orientation, but they can support additional orientations by setting the value of the allowedOrientations property. The ApplicationWindow changes the UI orientation as permitted by whichever Page is currently on top of the PageStack.

In order to provide a layout optimized for the currently selected orientation, the Page should refer to the orientation property, or the isPortrait and isLandscape properties which are provided to simplify layout declarations.

Whenever the UI orientation is changed, the orientationTransitions are applied to animate the transition. The default transition fades out the page, updates the affected properties (including orientation), then fades in the page in the new orientation. A Page may override the default transition to provide a custom animation. The default transition is provided by defaultOrientationTransition so that it may by used conditionally.

Property Documentation

allowedOrientations : enumeration

The set of orientations that the Page may be rotated to. The value may be any combination of:

  • Orientation.Portrait
  • Orientation.Landscape
  • Orientation.PortraitInverted
  • Orientation.LandscapeInverted

The following convenience values can be used as well:

  • Orientation.PortraitMask
  • Orientation.LandscapeMask
  • Orientation.All

The orientation of the user interface may be controlled by changing the allowedOrientations value. Whenever the device orientation changes, if the current device orientation is permitted by the allowedOrientations mask of the Page at the top of the PageStack, then that orientation will automatically be selected as the current user interface orientation.

When allowedOrientations is modified, if the current device orientation is permitted it will be immediately selected as the user interface orientation. Otherwise, the following sequence of orientations will be tested against the mask, and the first permitted orientation will be selected: Portrait, Landscape, LandscapeInverted, PortraitInverted.

The default value is Orientation.Portrait.

See also orientation and ApplicationWindow.deviceOrientation.

backNavigation : bool

This property holds whether the Page can be navigated backward.

The default value is true.

canNavigateForward : bool

This property holds whether the Page is ready to be navigated forward.

For instance, can be used when some data is missing from the Page and the data needs to be filled before forward navigation can take place.

See also forwardNavigation.

defaultOrientationTransition : Transition

The default transition used to animate changes of orientation.

See also orientation and orientationTransitions.

forwardNavigation : bool

This property holds whether the Page can be navigated forward.

By the default, this is true if the Page has an attached page and false otherwise.

See also canNavigateForward.

isLandscape : bool

This property is true if the current orientation has a landscape aspect.

See also orientation and isPortrait.

isPortrait : bool

This property is true if the current orientation has a portrait aspect.

See also orientation and isLandscape.

This property holds whether the Page follows vertical or horizontal navigation style.

  • PageNavigation.Horizontal
  • PageNavigation.Vertical

Horizontal navigation style is the most common, new page get pushed from the right and old pages returned from the left. Vertical navigation is useful when the Page already reserves horizontal flicking for another interactions, for example when the Page shows an image carousel that is scrolled horizontally. In vertical navigation the page can be back-stepped vertically from both directions, swiping up or down.

The default value is PageNavigation::Horizontal.

orientation : enumeration

The current orientation of the user interface.

  • Orientation.Portrait
  • Orientation.Landscape
  • Orientation.PortraitInverted
  • Orientation.LandscapeInverted

The following masks may be used to test for portrait or landscape, without regard for natural or inverted variants:

  • Orientation.PortraitMask
  • Orientation.LandscapeMask

This property describes the current orientation of the user interface as selected by the allowedOrientations mask. It may be used to tailor UI layout to match the current orientation. Changes to the orientation property are synchronized with the transition animation.

The default value is Orientation.Portrait.

See also allowedOrientations, isPortrait, isLandscape, and ApplicationWindow.

orientationTransitionRunning : bool

True if the orientation transition animation is currently running.

See also orientationTransitions.

orientationTransitions : list<Transition>

The list of transitions used to animate the transition from one orientation to another.

A custom transition should animate the transition between the following states:

  • "Portrait"
  • "Landscape"
  • "PortraitInverted"
  • "LandscapeInverted"

It should apply PropertyChanges to the following properties of the Page:

Finally, it should also toggle the state of orientationTransitionRunning before and after the transition animation operates.

See also defaultOrientationTransition.

pageContainer : Item

This property holds the PageStack which is managing this Page. If the page is not managed by a container, pageContainer is null.

showNavigationIndicator : bool

This property holds whether the Page navigation indicator will be shown or not. Even if true, the indicators will still only be shown if navigation is possible.

The default value is true.

status : enumeration

The status property holds the current status of the page within the PageStack.

  • PageStatus.Inactive - the page is not active in the page stack, and is not visible
  • PageStatus.Activating - the page is transitioning into becoming the active page
  • PageStatus.Active - the page is the current active page
  • PageStatus.Deactivating - the page is transitioning into becoming inactive

Note that changes to the application state do not affect the status of pages within the page stack.

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.