SafeArea QML Type

Provides access to the safe area properties of the item or window. More...

• List of all members, including inherited members

Properties

• additionalMargins
  • additionalMargins.bottom : real
  • additionalMargins.left : real
  • additionalMargins.right : real
  • additionalMargins.top : real
• margins
  • margins.bottom : real
  • margins.left : real
  • margins.right : real
  • margins.top : real

Detailed Description

The SafeArea attached type provides information about the areas of an Item or Window where content may risk being overlapped by other UI elements, such as system title bars or status bars.

This information can be used to lay out children of an item within the safe area of the item, while still allowing a background color or effect to span the entire item.

Rectangle { id: parentItem gradient: Gradient.SunnyMorning anchors.fill: parent Rectangle { id: childItem gradient: Gradient.DustyGrass anchors { fill: parent topMargin: parent.SafeArea.margins.top leftMargin: parent.SafeArea.margins.left rightMargin: parent.SafeArea.margins.right bottomMargin: parent.SafeArea.margins.bottom } } }

The SafeArea margins are relative to the item they attach to. If an ancestor item has laid out its children within the safe area margins, any descendant item with its own SafeArea attached will report zero margins, unless additional margins have been added.

Additional margins

Sometimes an item's layout involves child items that overlap each other, for example in a window with a semi transparent header, where the rest of the window content flows underneath the header.

In this scenario, the item may reflect the header's position and size to the child items via the additionalMargins property.

The additional margins will be combined with any margins that the item already picks up from its parent hierarchy (including system margins, such as title bars or status bars), and child items will reflect the combined margins accordingly.

Rectangle { id: parentItem gradient: Gradient.SunnyMorning anchors.fill: parent Rectangle { id: headerItem width: parent.width height: 80 + parent.SafeArea.margins.top gradient: Gradient.WinterNeva z: 1 } Item { id: contentItem anchors.fill: parent z: 0 SafeArea.additionalMargins.top: headerItem.height Rectangle { id: childItem gradient: Gradient.DustyGrass anchors { fill: parent topMargin: parent.SafeArea.margins.top leftMargin: parent.SafeArea.margins.left rightMargin: parent.SafeArea.margins.right bottomMargin: parent.SafeArea.margins.bottom } } } }

In the example above, the header item also takes safe area margins into account, to ensure there's enough room for its content, even when the header is partially covered by a title bar or status bar.

This will increase the height of the header, which is then reflected via the additional safe area margins to children of the content item.

Controls

Applying safe area margins to a Control is straightforward, as Control already offers properties to add padding to the control's content item.

Control {
    anchors.fill: parent

    background: Rectangle {
        gradient: Gradient.SunnyMorning
    }

    topPadding: SafeArea.margins.top
    leftPadding: SafeArea.margins.left
    rightPadding: SafeArea.margins.right
    bottomPadding: SafeArea.margins.bottom

    contentItem: Rectangle {
        gradient: Gradient.DustyGrass
    }
}

Property Documentation