Back to Doc.qt.io
Contact Us Blog Download Qt

WindowManager QML Type

The window model and controller. More...

Import Statement: import QtApplicationManager.SystemUI

Properties

Signals

Methods

Detailed Description

The WindowManager singleton type is the window managing part of the application manager. It provides a QML API only.

The type is derived from QAbstractListModel, and can be directly used as a model in window views.

Each item in this model corresponds to an actual window surface. Note that a single application can have multiple surfaces; therefore, the applicationId role is not unique within this model.

The following roles are available in this model:

Role nameTypeDescription
applicationIdstringThe unique id of an application represented as a string. This can be used to look up information about the application in the ApplicationManager model.
windowWindowObject The WindowObject containing the client surface. To display it you have to put it in a WindowItem
windowObjectWindowObjectExactly the same as window. This was added to keep the role names between the PackageManager and WindowManager models as similar as possible. This role was introduced in Qt version 6.6.
contentStateWindowObject::ContentState The content state of the WindowObject. See WindowObject::contentState

Note: Please be aware that Wayland is essentially an asynchronous IPC protocol, resulting in different local states in the client and server processes during state changes. A prime example for this is window property changes on the client side: in addition to being changed asynchronously on the server side, the windowPropertyChanged signal will not be emitted while the window object is not yet made available on the server side via the windowAdded signal. All those changes are not lost however, but the last change before emitting the windowAdded signal will be the initial state of the window object on the System UI side.

After importing, the WindowManager singleton can be used as in the example below. It demonstrates how to implement a basic, fullscreen window compositor with support for window show and hide animations:

import QtQuick
import QtApplicationManager.SystemUI

// Simple solution for a full-screen setup
Item {
    width: 1024
    height: 640

    Connections {
        target: WindowManager
        // Send windows to a separate model so that we have control
        // over removals and ordering
        function onWindowAdded(window) {
            windowsModel.append({"window":window});
        }
    }

    Repeater {
        model: ListModel { id: windowsModel }
        delegate: WindowItem {
            id: windowItem
            anchors.fill: parent
            z: model.index

            window: model.window

            states: [
                State {
                    name: "open"
                    when: model.window.contentState === WindowObject.SurfaceWithContent
                    PropertyChanges { target: windowItem; scale: 1; visible: true }
                }
            ]

            scale: 0.50
            visible: false

            transitions: [
                Transition {
                    to: "open"
                    NumberAnimation {
                        target: windowItem; property: "scale"
                        duration: 500; easing.type: Easing.OutQuad
                    }
                },
                Transition {
                    from: "open"
                    SequentialAnimation {
                        // we wanna see the window during the closing animation
                        PropertyAction { target: windowItem; property: "visible"; value: true }
                        NumberAnimation {
                            target: windowItem; property: "scale"
                            duration: 500; easing.type: Easing.InQuad
                        }
                        ScriptAction { script: {
                            // It's important to destroy our WindowItem once it's no longer needed in
                            // order to free up resources
                            if (model.window.contentState === WindowObject.NoSurface)
                                windowsModel.remove(model.index, 1);
                        } }
                    }
                }
            ]
        }
    }
}

Property Documentation

count : int [read-only]

This property holds the number of applications available.


runningOnDesktop : bool [read-only]

Holds true if running on a classic desktop window manager (Windows, X11, or macOS), false otherwise.


slowAnimations : bool

Whether animations are in slow mode.

It's false by default and might be initialized to true using the command line option --slow-animations.

Also useful to check this value if you need to adjust timings for the slow animation mode.


Signal Documentation

raiseApplicationWindow(string applicationId)

This signal is emitted when an application start is triggered for the already running application identified by applicationId via the ApplicationManager.

Note: The corresponding handler is onRaiseApplicationWindow.


windowAboutToBeRemoved(WindowObject window)

This signal is emitted before the window is removed from the model. This happens for instance, when the window visible property is set to false on the application side.

Note: The corresponding handler is onWindowAboutToBeRemoved.


windowAdded(WindowObject window)

This signal is emitted when a new WindowObject is added to the model. This happens in response to an application creating a new window surface, which usually occurs during that application's startup.

To display that window on your QML scene you need to assign it to a WindowItem.

Note: Please be aware that the windowAdded signal is not emitted immediately when the client sets a window to visible. This is due to the asynchronous nature of the underlying Wayland protocol.

Note: The corresponding handler is onWindowAdded.


windowContentStateChanged(WindowObject window)

This signal is emitted when the WindowObject::contentState of the given window changes.

Note: The corresponding handler is onWindowContentStateChanged.

See also WindowObject::contentState.


windowPropertyChanged(WindowObject window, string name, var value)

Reports a change of an application window's property identified by name to the given value.

Note: When listening to property changes of Wayland clients, be aware of the asynchronous nature of the underlying Wayland protocol.

Note: The corresponding handler is onWindowPropertyChanged.

See also ApplicationManagerWindow::setWindowProperty().


Method Documentation

object addExtension(Component component)

Creates a Wayland compositor extension from component and adds it to the System UI's underlying WaylandCompositor. The component must hold a valid Wayland compositor extension. On success, in multi-process mode, the function returns the created extension. Extensions can only be added, once ApplicationManager::windowManagerCompositorReady is true, for example:

import QtWayland.Compositor.TextureSharingExtension

Component {
    id: texshare
    TextureSharingExtension {}
}

Connections {
    target: ApplicationManager
    function onWindowManagerCompositorReadyChanged() {
        WindowManager.addExtension(texshare);
    }
}

See also ApplicationManager::windowManagerCompositorReady.


object get(int index)

Retrieves the model data at index as a JavaScript object. See the role names for the expected object fields.

Returns an empty object if the specified index is invalid.


int indexOfWindow(WindowObject window)

Returns the index of the window within the WindowManager model, or -1 if the window item is not a managed window.


bool makeScreenshot(string filename, string selector)

Creates one or several screenshots depending on the selector, saving them to the files specified by filename.

The filename argument can either be a plain file name for single screenshots, or it can contain format sequences that will be replaced accordingly, if multiple screenshots are requested:

FormatDescription
%sWill be replaced with the screen-id of this particular screenshot.
%iWill be replaced with the application id, when making screenshots of application windows.
%%Will be replaced by a single % character.

The selector argument is a string which is parsed according to this pattern:

<application-id>[window-property=value]:<screen-id>

All parts are optional, so if you specify an empty string, the call will create a screenshot of every screen. If you specify an application-id (which can also contain wildcards for matching multiple applications), a screenshot will be made for each window of this (these) application(s). If only specific windows of one or more applications should be used to create screenshots, you can specify a window-property selector, which will only select windows that have a matching WindowManager::windowProperty. Adding a screen-id will restrict the creation of screenshots to the the specified screen.

Here is an example, creating screenshots of all windows on the second screen, that have the window-property type set to cluster and written by Pelagicore:

com.pelagicore.*[type=cluster]:1

Returns true on success and false otherwise.

Note: This call will be handled asynchronously, so even a positive return value does not mean that all screenshot images have been created already.


WindowObject window(int index)

Returns the window corresponding to the given index in the model, or null if the index is invalid.

Note: The object ownership of the returned Window object stays with the application manager. If you want to store this pointer, you can use the WindowManager's QAbstractListModel signals or the windowAboutToBeRemoved signal to get notified if the object is about to be deleted on the C++ side.


list<WindowObject> windowsOfApplication(string applicationId)

Returns a list of windows belonging to the given applicationId in the model, or an empty list if the applicationId is invalid.

Note: The object ownership of the returned Window objects stays with the application manager. If you want to store these pointers, you can use the WindowManager's QAbstractListModel signals or the windowAboutToBeRemoved signal to get notified if the objects are about to be deleted on the C++ side.


© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.