- Qt 6.8
- Qt Wayland Compositor
- QML Types
- QtWayland.Compositor.QtShell
- QtShellChrome
- Qt Wayland Compositor | Commercial or GPLv3

# QtShellChrome QML Type

Provides default window manager functionality for use with the `qt-shell` extension. More...

Import Statement: | import QtWayland.Compositor.QtShell
Since: | Qt 6.3

- List of all members, including inherited members

## Properties

- bottomLeftResizeHandle : Item
- bottomResizeHandle : Item
- bottomRightResizeHandle : Item
- frameMarginBottom : int
- frameMarginLeft : int
- frameMarginRight : int
- frameMarginTop : int
- hasDecorations : bool
- leftResizeHandle : Item
- maximizedRect : rect
- rightResizeHandle : Item
- shellSurfaceItem : ShellSurfaceItem
- titleBar : Item
- topLeftResizeHandle : Item
- topResizeHandle : Item
- topRightResizeHandle : Item
- windowFlags : int
- windowState : int

## Methods

- void activate()
- void deactivate()
- void lower()
- void raise()
- void toggleFullScreen()
- void toggleMaximized()
- void toggleMinimized()

## Detailed Description

The QtShellChrome is a convenience type that can be used to provide window manager functionality to the interaction with clients over the `qt-shell` shell extension protocol.

Given a ShellSurfaceItem with an associated QtShellSurface, the item will automatically adapt its size to match the surface. It will also provide automatic handling of:

- Window states, such as maximized, minimized and fullscreen.
- Window activation.
- Window resizing using with resize handles (if the appropriate properties are set.)
- Window repositioning using title bar interaction (if the titleBar property is set.)

The QtShellChrome is intended to be used together with QtShell and QtShellSurface.

See also QtShell Compositor.

## Property Documentation

bottomLeftResizeHandle : Item

This property holds the default bottom-left resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its bottom and left edges in equal amounts.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: blrh
            anchors.bottom: parent.bottom
            anchors.left: parent.left
            height: 5
            width: 5
            color: "white"
        }
        bottomLeftResizeHandle: blrh
     }

bottomResizeHandle : Item

This property holds the default bottom resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its bottom edge.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: brh
            anchors.bottom: parent.bottom
            anchors.left: parent.left
            anchors.right: parent.right
            height: 5
            color: "white"
        }
        bottomResizeHandle: brh
     }

Note: Unless explicit frame margins are set, the handle's height will be included in the window's bottom frame margin.

bottomRightResizeHandle : Item

This property holds the default bottom-right resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its bottom and right edges in equal amounts.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: brrh
            anchors.bottom: parent.bottom
            anchors.right: parent.right
            height: 5
            width: 5
            color: "white"
        }
        bottomRightResizeHandle: brrh
     }

frameMarginBottom : int

Sets the size of the bottom margin of the QtShellChrome which is reserved for window decorations. By default, this will equal the height of the bottomResizeHandle if it is set. Otherwise it will be 0.

Note: By setting this property explicitly, all default frame margins will be overridden with their corresponding properties.

frameMarginLeft : int

Sets the size of the left margin of the QtShellChrome which is reserved for window decorations. By default, this will equal the width of the leftResizeHandle if it is set. Otherwise it will be 0.

Note: By setting this property explicitly, all default frame margins will be overridden with their corresponding properties.

frameMarginRight : int

Sets the size of the right margin of the QtShellChrome which is reserved for window decorations. By default, this will equal the width of the rightResizeHandle if it is set. Otherwise it will be 0.

Note: By setting this property explicitly, all default frame margins will be overridden with their corresponding properties.

frameMarginTop : int

Sets the size of the top margin of the QtShellChrome which is reserved for window decorations. By default, this will equal the sum of the leftResizeHandle and the titleBar's heights, if they are set. Otherwise it will be 0.

Note: By setting this property explicitly, all default frame margins will be overridden with their corresponding properties.

hasDecorations : bool `[read-only]`

This property is true if the QtShellChrome's decorations should be visible, based on its window state and window flags.

leftResizeHandle : Item

This property holds the default left resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its left edge.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: lrh
            anchors.left: parent.left
            anchors.top: parent.top
            anchors.bottom: parent.bottom
            width: 5
            color: "white"
        }
        leftResizeHandle: lrh
     }

Note: Unless explicit frame margins are set, the handle's width will be included in the window's left frame margin.

maximizedRect : rect

This property holds the are of the WaylandOutput which is available to be filled by the window when it is in maximized state. By default, the window will fill the entire geometry of the WaylandOutput when it is maximized. Changing it can be useful for example when the compositor has other system UI which should not be obscured by maximized applications, such as a task bar.

rightResizeHandle : Item

This property holds the default right resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its right edge.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: rrh
            anchors.right: parent.right
            anchors.top: parent.top
            anchors.bottom: parent.bottom
            width: 5
            color: "white"
        }
        rightResizeHandle: rrh
     }

Note: Unless explicit frame margins are set, the handle's width will be included in the window's right frame margin.

shellSurfaceItem : ShellSurfaceItem

This property holds the shell surface item associated with this QtShellChrome. It will in turn manage the `shellSurface` of this item. The `shellSurface` of the item is expected to be of the type QtShellSurface.

     QtShellChrome {
        id: chrome
        ShellSurfaceItem {
            id: sfi
            anchors.fill: parent
            moveItem: chrome
        }
        shellSurfaceItem: sfi
     }

titleBar : Item

This property holds the default title bar item of the QtShellChrome. If set, a DragHandler will be installed on the title bar which moves the window around on user interaction. In addition, the window will automatically be activated if the title bar is clicked.

The title bar will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: tb
            anchors.top: parent.top
            anchors.right: parent.right
            anchors.left: parent.left
            height: 50
            color: "black"

            Text {
                color: "white"
                anchors.centerIn: parent
                text: shellSurfaceItem.shellSurface.windowTitle
                font.pixelSize: 25
            }
        }
        titleBar: tb
     }

Note: Unless explicit frame margins are set, the title bar's height will be included in the window's top frame margin.

topLeftResizeHandle : Item

This property holds the default top-left resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its top and left edges in equal amounts.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: tlrh
            anchors.top: parent.top
            anchors.left: parent.left
            height: 5
            width: 5
            color: "white"
        }
        topLeftResizeHandle: tlrh
     }

topResizeHandle : Item

This property holds the default top resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its top edge.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: trh
            anchors.top: parent.top
            anchors.left: parent.left
            anchors.right: parent.right
            height: 5
            color: "white"
        }
        topResizeHandle: trh
     }

Note: Unless explicit frame margins are set, the handle's height will be included in the window's top frame margin.

topRightResizeHandle : Item

This property holds the default top-right resize handle of the QtShellChrome. If set, a DragHandler will be installed on the resize handle which resizes the window by moving its top and right edges in equal amounts.

The handle will automatically hide and show, depending on the window flags and the window's full screen state.

     QtShellChrome {
        Rectangle {
            id: trrh
            anchors.top: parent.top
            anchors.right: parent.right
            height: 5
            width: 5
            color: "white"
        }
        topRightResizeHandle: trrh
     }

windowFlags : int `[read-only]`

This property holds the window flags of the QtShellChrome. They will match the `windowFlags` property of the associated QtShellSurface, except when this is equal to Qt.Window. In this case, a set of default window flags will be used instead. The default window flags are Qt.Window, Qt.WindowMaximizeButtonHint, Qt.WindowMinimizeButtonHint and Qt.WindowCloseButtonHint.

windowState : int `[read-only]`

This property holds the window state of the shell surface. It will be updated immediately when the window state is requested on the compositor-side, before this has been acknowledged by the client. Therefore, it may in brief periods differ from the shell surface's `windowState` property, which will be updated when the client has acknowledged the request.

## Method Documentation

void activate()

Manually activate this window. This will also raise the window.

See also raise().

void deactivate()

Manually deactivates this window. If the window was active, this will activate the next window in the stack instead.

void lower()

Lower this window, so that it stacks underneath other windows (except if the other window's window flags prohibit this.)

void raise()

Raise this window, so that it stacks on top of other windows (except if the other window's flags prohibit this.)

void toggleFullScreen()

Toggles between fullscreen and normal window states. This method also clears the minimized or maximized window states if either is set.

void toggleMaximized()

Toggles between maximized and normal states. This method also clears the minimized window state if it is set.

void toggleMinimized()

Toggles between minimized and normal states. This method also clears the maximized window state if it is set.