SplitView QML Type | Qt Quick Controls 6.1.2

- Qt 6.1
- Qt Quick Controls
- QML Types
- SplitView QML Type
- Qt 6.1.2 Reference Documentation

# SplitView QML Type

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

Import Statement: | import QtQuick.Controls 2.1
Since: | Qt 5.13
Inherits: | Container

- 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
     import Qt.labs.settings

     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
     import Qt.labs.settings

     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

handle : Component

This property holds the handle component.

An instance of this component will be instantiated `count - 1` times, as long as `count` is greater than than `1`.

The following table explains how each handle will be resized depending on the orientation of the split view:

Orientation | Handle Width | Handle Height
--- | --- | ---
`Qt.Horizontal` | `implicitWidth` | The `height` of the SplitView.
`Qt.Vertical` | The `width` of the SplitView. | `implicitHeight`

See also Customizing SplitView.

orientation : enumeration

This property holds the orientation of the SplitView.

The orientation determines how the split items are laid out:

Possible values:

Constant | Description
--- | ---
`Qt.Horizontal` | The items are laid out horizontally (default).
`Qt.Vertical` | The items are laid out vertically.

[read-only] resizing : bool

This property is `true` when the user is resizing split items by dragging on the splitter handles.

## Attached Property Documentation

SplitView.fillHeight : bool

This attached property controls whether the item takes the remaining space in the split view after all other items have been laid out.

By default, the last visible child of the split view will have this set, but it can be changed by explicitly setting `fillHeight` to `true` on another item.

The height of a split item with `fillHeight` set to `true` is still restricted within its minimumHeight and maximumHeight.

See also minimumHeight, preferredHeight, maximumHeight, and fillWidth.

SplitView.fillWidth : bool

This attached property controls whether the item takes the remaining space in the split view after all other items have been laid out.

By default, the last visible child of the split view will have this set, but it can be changed by explicitly setting `fillWidth` to `true` on another item.

The width of a split item with `fillWidth` set to `true` is still restricted within its minimumWidth and maximumWidth.

See also minimumWidth, preferredWidth, maximumWidth, and fillHeight.

SplitView.maximumHeight : real

This attached property controls the maximum height of the split item. The preferredHeight is bound within the minimumHeight and maximumHeight. A split item cannot be dragged to be larger than its `maximumHeight`.

The default value is `Infinity`. To reset this property to its default value, set it to `undefined`.

See also minimumHeight, preferredHeight, fillHeight, and maximumWidth.

SplitView.maximumWidth : real

This attached property controls the maximum width of the split item. The preferredWidth is bound within the minimumWidth and maximumWidth. A split item cannot be dragged to be larger than its `maximumWidth`.

The default value is `Infinity`. To reset this property to its default value, set it to `undefined`.

See also minimumWidth, preferredWidth, fillWidth, and maximumHeight.

SplitView.minimumHeight : real

This attached property controls the minimum height of the split item. The preferredHeight is bound within the minimumHeight and maximumHeight. A split item cannot be dragged to be smaller than its `minimumHeight`.

The default value is `0`. To reset this property to its default value, set it to `undefined`.

See also maximumHeight, preferredHeight, fillHeight, and minimumWidth.

SplitView.minimumWidth : real

This attached property controls the minimum width of the split item. The preferredWidth is bound within the minimumWidth and maximumWidth. A split item cannot be dragged to be smaller than its `minimumWidth`.

The default value is `0`. To reset this property to its default value, set it to `undefined`.

See also maximumWidth, preferredWidth, fillWidth, and minimumHeight.

SplitView.preferredHeight : real

This attached property controls the preferred height of the split item. The preferred height will be used as the size of the item, and will be bound within the minimumHeight and maximumHeight. If the preferred height is not set, the item's implicitHeight will be used.

When a split item is resized, the preferredHeight will be set in order to keep track of the new size.

By default, this property is not set, and therefore implicitHeight will be used instead. To reset this property to its default value, set it to `undefined`.

Note: Do not set the height property of a split item, as it will be overwritten upon each layout of the SplitView.

See also minimumHeight, maximumHeight, fillHeight, and preferredWidth.

SplitView.preferredWidth : real

This attached property controls the preferred width of the split item. The preferred width will be used as the size of the item, and will be bound within the minimumWidth and maximumWidth. If the preferred width is not set, the item's implicitWidth will be used.

When a split item is resized, the preferredWidth will be set in order to keep track of the new size.

By default, this property is not set, and therefore implicitWidth will be used instead. To reset this property to its default value, set it to `undefined`.

Note: Do not set the width property of a split item, as it will be overwritten upon each layout of the SplitView.

See also minimumWidth, maximumWidth, fillWidth, and preferredHeight.

SplitView.view : SplitView

This attached property holds the split view of the item it is attached to, or `null` if the item is not in a split view.

## Method Documentation

bool restoreState(state)

Reads the preferred sizes from state and applies them to the split items.

Returns `true` if the state was successfully restored, otherwise `false`.

See also Serializing SplitView's State and saveState().

var saveState()

Saves the preferred sizes of split items into a byte array and returns it.

See also Serializing SplitView's State and restoreState().