API Documentation

Documentation for developing SailfishOS applications

ApplicationWindow QML Type

The top-level component of a Sailfish application More...

Import Statement:	import Sailfish.Silica 1.0
Inherits:	SilicaControl

Properties

allowedOrientations : enumeration
background.color : color (preliminary)
background.filter : string (preliminary)
background.image : url (preliminary)
background.material : string (preliminary)
background.wallpaper : var (preliminary)
bottomMargin : real
contentItem : Item
cover : var
defaultAllowedOrientations : enumeration
deviceOrientation : enumeration
initialPage : var
orientation : enumeration
pageStack : PageStack
screenRotation : real

Methods

activate()
deactivate()

Detailed Description

The ApplicationWindow type is used to create the top-level item in a Sailfish application.

Every Sailfish application must have a single ApplicationWindow component defined at the root of its hierarchy. An application window is the entry point for the loading of the application.

The ApplicationWindow type allows an application to:

Manage the pages in the application page stack
Set the application's active cover page
Set the application's background wallpaper image
Handle orientation changes to update the UI as appropriate

The most basic application window consists of a single initialPage that specifies the page that is displayed when the application is opened:

 import Sailfish.Silica 1.0

 ApplicationWindow {
     initialPage: Component {
         Page {
             Text { text: "Ahoy!" }
         }
     }
 }

Hierarchical navigation with the application page stack

Each application window contains a single page stack, accessible through the pageStack property, that determines the content to be displayed by the application. The stack is made up of Page objects: each page contains the content to be displayed by the application at any one time. A content page can be pushed (added) to a stack, or popped (removed) from a stack. The top-most page — that is, the page that was last pushed onto the stack — is the page that is currently visible within the application window.

Below is a basic application that initially displays a page containing a single Button. When the button is clicked, the Page defined by AnotherPage.qml is pushed onto the page stack, becoming the top-most page displayed by the application:

 // main.qml
 import QtQuick 2.2
 import Sailfish.Silica 1.0

 ApplicationWindow {
     initialPage: Component {
         Page {
             Button {
                 text: "Ahoy!"
                 onClicked: pageStack.push("AnotherPage.qml")
             }
         }
     }
 }

 // AnotherPage.qml
 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Page {
     Button {
         text: "close this page"
         onClicked: pageStack.pop()
     }
 }

For further details on modifying the page stack, see the PageStack documentation.

Active covers: providing application status on the home screen

Each Sailfish application may specify its own active cover through the cover property. An active cover is a visual representation of the application that is displayed in the Jolla home screen when the application is backgrounded. A cover may, for example, show application status information, and optionally allow cover interaction for the most common application actions.

For example:

 ApplicationWindow {
     initialPage: Component { MyPage {} }
     cover: Component { MyCover {} }
 }

The cover must be capable of scaling as it may be resized by the launcher depending upon the number of applications running in the background. If the cover provides actions then a CoverActionList must be provided.

Enabling orientation changes

An application may permit the orientation of the user interface to follow the orientation changes of the device, or it may constrain the user interface to a single orientation by modifying the allowedOrientations property.

The orientation property reflects the current UI orientation and may be used to create an optimal layout for the prevailing orientation.

Applications using the PageStack should prefer to use the functionality exported by the Page component to support multiple orientations.

Property Documentation

allowedOrientations : enumeration

The set of orientations that the interface 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 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 allowedOrientations property can be bound to defaultAllowedOrientations if the application wants to follow the defaul orientation behavior of the platfrom applications. Notice that the value of defaultAllowedOrientations depends on the device configuration.

When using a PageStack, an application may set this property to restrict the set of possible orientations for all pages in the PageStack. The effective orientation is then selected from the intersection of the allowed orientations for the ApplicationWindow and for the Page that is the current top of the stack. If the current Page requires an orientation that the ApplicationWindow property does not allow, however, the Page orientation will be given precedence.

The default value is Orientation.All.

background.color : color