API Documentation

Documentation for developing SailfishOS applications

Cover QML Type

An application cover More...

Import Statement: import Sailfish.Silica 1.0
Inherited By:

CoverBackground

Properties

Detailed Description

An application cover is a representation of the app that is displayed in the Sailfish OS Home screen when the app is minimized.

Covers are used to display essential application information or other details that convey the purpose and status of the application. For example, a Mail app may show the number of unread emails, or a Gallery app may show thumbnail images of random photos from the user's collection. A cover may alo have one or more cover actions to allow the user to interact with and perform essential actions on the application while it is minimized.

The application cover is set with the ApplicationWindow cover property.

Below is a simple app that shows a DatePicker. When the app is minimized to the Home screen, the selected date is shown on the app cover:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 ApplicationWindow {
     initialPage: Component {
         Page {
             property string selectedDate: datePicker.dateText

             PageHeader {
                 id: header
                 title: datePicker.dateText
             }
             DatePicker {
                 id: datePicker
                 anchors.top: header.bottom
             }
         }
     }

     cover: Component {
         Cover {
             transparent: true

             Label {
                 anchors.centerIn: parent
                 font.pixelSize: Theme.fontSizeLarge
                 text: pageStack.currentPage.selectedDate
             }
         }
     }
 }

Designing effective app covers

Covers are an effective way of conveying significant information that is unique to your application. An app cover should provide essential information and actions in a concise manner and it should be presented in a manner that distinguishes your app on the Home screen.

Here are a few tips for designing effective app covers:

  • A cover should represent your app in an identifiable manner that conveys its essential purpose. For example, the Sailfish Gallery app cover shows images within polaroid photo frames, the Sailfish Maps cover shows a fullscreen map image, and the Sailfish Weather cover shows a large graphic representing the current weather conditions. The user needs to recognise your app among the others shown on the Home screen, so make it unique.
  • Cover information should be concise and able to be interpreted at a glance; detailed information should be reserved for the main app UI when it is returned to the foreground as the main app, rather than cluttering the cover. Remember the cover display may be scaled down if the Home screen is showing a large number of app covers at the same time, which will make it difficult to read small details.
  • Consider changing a cover depending on the current status of the application to show more precise information. For example, when the Sailfish Gallery app is showing the main photo browser view, its cover shows a scattering of random images from the collection; when the app is showing a single image in fullscreen mode, its cover shows only this image and expands it to the full size of the cover.
  • Since covers may be scaled to a small size, font sizes smaller than Theme.fontSizeMedium should generally be avoided. It may also be useful to fade or truncate content due to the limited visual space.
  • Cover text and monochromatic icons should typically be colored with Theme.primaryColor, with Theme.highlightColor reserved for drawing attention to significant information.

If a cover displays textual content rather than graphical content that fills the entire cover, the text should be separated from the cover edges with Theme.paddingLarge on the left and right sides and Theme.paddingMedium on the top and bottom.

Selectively enabling CPU-intensive operations

Covers that run animations, timers or other CPU-intensive operations must ensure these are only enabled when the cover is being shown in the Home screen, and even then, they must be run infrequently; a Home screen full of covers with CPU-intensive operations will drain system resources and impact general performance.

For instance, a Weather app cover that shows the current weather conditions only needs to update this graphic when the server has notified the app about a change in conditions, and a Mail app cover with the unread mail count only needs to update this when the mail account has been synchronized with the server. A Gallery app with a cover that animates a slideshow of thumbnail images would have more frequent graphical cover updates, but to preserve system resources, it could only trigger the animation every thirty seconds, and of course only when the cover is actually shown.

The status property is used to test whether the cover is being shown in the Home screen. For example, the cover below only enables its animation when the status is Cover.Active, and also pauses the animation for 30 seconds during each sequence to avoid excessive rendering updates when shown:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Cover {
     id: cover
     anchors.fill: parent
     transparent: true

     Label {
         anchors.centerIn: parent
         text: cover.status == Cover.Active ? "I'm active!" : "I'm sleeping"

         SequentialAnimation on rotation {
             running: cover.status == Cover.Active
             loops: Animation.Infinite

             RotationAnimation {
                 duration: 2000
                 from: 0; to: 360
             }

             PauseAnimation { duration: 30 * 1000 }
         }
     }
 }

See also CoverBackground and Sailfish Application Features.

Property Documentation

allowResize : bool

This property defines whether the cover supports being resized. If set to false, which is the default, the cover should assume its size is equal to Theme.coverSizeLarge, and, if needed, it will be scaled. If set to true the cover must rearrange its items to better fit in the available space.


coverActionArea : Item

This convenience property represents the area reserved for the cover actions that Homescreen shows on top of application's active cover. The area is exposed as an item, which can be anchored to, or whose geometry read from its properties like y position or height.

Try to avoid displaying content below the action icons when they are visible or use CoverActionList.iconBackground API to add gradient below the icons.


size : enumeration

This property holds the current size of the cover. The value should be one of:


status : enumeration

This property holds the current status of the cover, indicating whether it is visible on the home screen.

  • Cover.Inactive - the cover is not active, the user cannot interact with the cover, and it is not visible unless the user is peeking
  • Cover.Activating - the cover is transitioning into becoming active
  • Cover.Active - the cover is visible, and the user can interact with it
  • Cover.Deactivating - the cover is transitioning into becoming inactive

transparent : bool

This property holds whether the cover background is transparent.

If true, the Sailfish OS cover background will be visible.

See also CoverBackground.


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.