SafeArea QML Type

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

Import Statement: import QtQuick
Since: Qt 6.9

Properties

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.

Note: An item should not be positioned based on its own safe area, as that would result in a binding loop.

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.

Note: In this example the header item does not overlap the child item, as the goal is to show how the items are positioned and resized in response to safe area margin changes.

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

additionalMargins group

additionalMargins.bottom : real

additionalMargins.left : real

additionalMargins.right : real

additionalMargins.top : real

This property holds the additional safe area margins for the item.

The resulting safe area margins of the item are the maximum of any inherited safe area margins (for example from title bars or status bar) and the additional margins applied to the item.

See also margins.


margins group

margins.bottom : real [read-only]

margins.left : real [read-only]

margins.right : real [read-only]

margins.top : real [read-only]

This property holds the safe area margins, relative to the attached item.

See also additionalMargins.