API Documentation
Documentation for developing SailfishOS applicationsPage QML Type
A single page within an application More...
| Import Statement: | import Sailfish.Silica 1.0 |
| Inherits: | |
| Inherited By: | ColorPickerPage, DatePickerDialog, Dialog, and TimePickerDialog |
Properties
- allowedOrientations : enumeration
- backNavigation : bool
- background : Component
(preliminary) - backgroundColor : color
(preliminary) - canNavigateForward : bool
- defaultOrientationTransition : Transition
- forwardNavigation : bool
- highContrast : bool
(preliminary) - isLandscape : bool
- isPortrait : bool
- navigationStyle : enumeration
- orientation : enumeration
- orientationTransitionRunning : bool
- orientationTransitions : list<Transition>
- pageContainer : Item
- showNavigationIndicator : bool
- status : enumeration
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
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.
This property holds whether the Page can be navigated backward.
The default value is true.
This QML property is under development and is subject to change.
The background of a Page.
Page backgrounds are constructed behind a page item and are excluded from some transformations like ambience and orientation change fade transitions which would normally cause the application background to temporarily be shown.
Some items like DialogHeader hide content which scrolls behind the item by constructing a copy of the page background as such it's important to use an item with position independent rendering like the Sailfish.Silica.Background Background so these smaller cropped items draw the same content as the larger full page item behind them.
The ApplicationWindow::background.wallpaper and ApplicationWindow::background.image properties may also be used to set an application wide background.
This QML property is under development and is subject to change.
The background color of a page.
By default this is transparent and the application background will be visible behind the page.
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.
The default transition used to animate changes of orientation.
See also orientation and orientationTransitions.
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.
This QML property is under development and is subject to change.
Increases the contrast between the application background and foreground text.
Useful for text input and reading heavy pages where you want high contrast to maximise the legibility.
This property is true if the current orientation has a landscape aspect.
See also orientation and isPortrait.
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.
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.
True if the orientation transition animation is currently running.
See also orientationTransitions.
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:
- orientation
- rotation
- width
- height
Finally, it should also toggle the state of orientationTransitionRunning before and after the transition animation operates.
See also defaultOrientationTransition.
This property holds the PageStack which is managing this Page. If the page is not managed by a container, pageContainer is null.
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.
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.