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

Properties

Methods

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.

See also orientation, defaultAllowedOrientations, deviceOrientation, and Page.


bottomMargin : real

Specifies the margin between the page stack and the bottom of the application window. The default value is 0.0.

This may be used, for example, to show floating controls that are always visible regardless of the page displayed.

Note: the area reserved is the larger of the bottomMargin and the input panel. If an input panel is shown then the content displayed in bottomMargin will be covered.


contentItem : Item

The internal item containing children of the application window.

The children of the application window are parented to the contentItem. The size and the position of the contentItem matches the size and the position of the current page, but the coordinates of the contentItem do not rotate. Generally, it is recommended to place all the content within a page as it handles the coordinate changes correctly. The items that are direct children of the application window need to take care of orientation changes themselves.


cover : var

Specifies the cover that is displayed when the application is backgrounded and displayed in the home screen. A cover typically displays the current status of the application. The home screen will resize the cover depending on the number of opened applications, so the cover must be scalable.

The cover should be a Component with a top-level Cover, or a URL referring to the component to be loaded. It can also be a cover instance but this is not recommended as the cover will be loaded before it is required to be shown.

A cover may also allow interaction via CoverActionList.


[read-only] defaultAllowedOrientations : enumeration

The default allowed orientations of the device. The value may be any combination of:

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

The value depends on the device configuration. Typically a tablet device would include all orientations but a phone would exclude the inverted portrait orientation.

See also orientation and allowedOrientations.


deviceOrientation : enumeration

The current orientation of the device.

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

This property reflects the current orientation of the device. It changes as the device is physically manipulated.

See also orientation and allowedOrientations.


initialPage : var

Specifies the page that is displayed when the application is opened. This may be a Page object, a Component that defines a Page-type component, or the url of a Page-type component to be loaded.

Note that if you provide an explicit instantiation, as in this example:

 ApplicationWindow {
     initialPage: Page {
         // ...
     }
 }

then the Page component is instantiated without a parent (since the ApplicationWindow itself will not have been instantiated yet), which means that any properties dependent on the parent will have to be re-evaluated after the ApplicationWindow is instantiated.

It is preferable to supply a component that can be used to instantiate the page after the ApplicationWindow has been instantiated. For example, the previous example should become:

 ApplicationWindow {
     initialPage: Component {
         Page {
             // ...
         }
     }
 }

See also PageStack::push().


[read-only] 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.

An application using the PageStack should not use this value directly — the orientation property of the Page component should be used to layout Page elements, since it changes in sync with the orientation transition animation.

See also allowedOrientations, deviceOrientation, and Page.


pageStack : PageStack

Holds the pages displayed in the application.

The initialPage will be automatically added to the pageStack. Additional pages may be pushed to or popped from the stack.

See also PageStack.


screenRotation : real

The angle of rotation that is applied to align the portrait-aspect user interface with the native device coordinates.

The screenRotation is initially read from the GConf key /desktop/jolla/components/screen_rotation_angle. It may also be modified at run time. Only multiples of 90 degrees produce valid rotations.


Method Documentation

activate()

Brings the application to the foreground in full-screen mode.


deactivate()

Sends the application to the background. The minimized application is displayed as an active cover on the homescreen.


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.