SplitView QML Type

Lays out items with a draggable splitter between each item. More...

• List of all members, including inherited members

Properties

• handle : Component
• orientation : enumeration
• resizing : bool

Attached Properties

• fillHeight : bool
• fillWidth : bool
• maximumHeight : real
• maximumWidth : real
• minimumHeight : real
• minimumWidth : real
• preferredHeight : real
• preferredWidth : real
• view : SplitView

Methods

• bool restoreState(state)
• var saveState()

Detailed Description

SplitView is a control that lays out items horizontally or vertically with a draggable splitter between each item.

SplitView supports the following attached properties on items it manages:

• SplitView.minimumWidth
• SplitView.minimumHeight
• SplitView.preferredWidth
• SplitView.preferredHeight
• SplitView.maximumWidth
• SplitView.maximumHeight
• SplitView.fillWidth (true for only one child)
• SplitView.fillHeight (true for only one child)

In addition, each handle has the following read-only attached properties:

• SplitHandle.hovered
• SplitHandle.pressed

Note: Handles should be purely visual and not handle events, as it can interfere with their hovered and pressed states.

The preferred size of items in a SplitView can be specified via implicitWidth and implicitHeight or SplitView.preferredWidth and SplitView.preferredHeight:

 SplitView {
     anchors.fill: parent

     Item {
         SplitView.preferredWidth: 50
     }

     // ...
 }

For a horizontal SplitView, it's not necessary to specify the preferred height of each item, as they will be resized to the height of the view. This applies in reverse for vertical views.

When a split handle is dragged, the SplitView.preferredWidth or SplitView.preferredHeight property is overwritten, depending on the orientation of the view.

To limit the size of items in a horizontal view, use the following properties:

 SplitView {
     anchors.fill: parent

     Item {
         SplitView.minimumWidth: 25
         SplitView.preferredWidth: 50
         SplitView.maximumWidth: 100
     }

     // ...
 }

To limit the size of items in a vertical view, use the following properties:

 SplitView {
     anchors.fill: parent
     orientation: Qt.Vertical

     Item {
         SplitView.minimumHeight: 25
         SplitView.preferredHeight: 50
         SplitView.maximumHeight: 100
     }

     // ...
 }

There will always be one item (the fill item) in the SplitView that has SplitView.fillWidth set to true (or SplitView.fillHeight, if orientation is Qt.Vertical). This means that the item will get all leftover space when other items have been laid out. By default, the last visible child of the SplitView will have this set, but it can be changed by explicitly setting fillWidth to true on another item.

A handle can belong to the item either on the left or top side, or on the right or bottom side:

• If the fill item is to the right: the handle belongs to the left item.
• If the fill item is on the left: the handle belongs to the right item.

To create a SplitView with three items, and let the center item get superfluous space, one could do the following:

 SplitView {
     anchors.fill: parent
     orientation: Qt.Horizontal

     Rectangle {
         implicitWidth: 200
         SplitView.maximumWidth: 400
         color: "lightblue"
         Label {
             text: "View 1"
             anchors.centerIn: parent
         }
     }
     Rectangle {
         id: centerItem
         SplitView.minimumWidth: 50
         SplitView.fillWidth: true
         color: "lightgray"
         Label {
             text: "View 2"
             anchors.centerIn: parent
         }
     }
     Rectangle {
         implicitWidth: 200
         color: "lightgreen"
         Label {
             text: "View 3"
             anchors.centerIn: parent
         }
     }
 }

Serializing SplitView's State

The main purpose of SplitView is to allow users to easily configure the size of various UI elements. In addition, the user's preferred sizes should be remembered across sessions. To achieve this, the values of the SplitView.preferredWidth and SplitView.preferredHeight properties can be serialized using the saveState() and restoreState() functions:

 import QtQuick.Controls 2.15
 import Qt.labs.settings 1.0

 ApplicationWindow {
     // ...

     Component.onCompleted: splitView.restoreState(settings.splitView)
     Component.onDestruction: settings.splitView = splitView.saveState()

     Settings {
         id: settings
         property var splitView
     }

     SplitView {
         id: splitView
         // ...
     }
 }

Alternatively, the value() and setValue() functions of Settings can be used:

 import QtQuick.Controls 2.15
 import Qt.labs.settings 1.0

 ApplicationWindow {
     // ...

     Component.onCompleted: splitView.restoreState(settings.value("ui/splitview"))
     Component.onDestruction: settings.setValue("ui/splitview", splitView.saveState())

     Settings {
         id: settings
     }

     SplitView {
         id: splitView
         // ...
     }
 }

See also SplitHandle, Customizing SplitView, and Container Controls.

Property Documentation

Attached Property Documentation

Method Documentation