Qt Documentation

Contents

WindowManager QML Type

The window model and controller. More...

Import Statement: import QtApplicationManager.SystemUI 2.0

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.
window WindowObjectThe WindowObject containing the client surface. To display it you have to put it in a WindowItem
contentState WindowObject::ContentStateThe 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 2.10
import QtApplicationManager.SystemUI 2.0

// 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
        onWindowAdded: 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

[read-only] count : int

This property holds the number of applications available.


[read-only] runningOnDesktop : bool

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(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(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(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(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(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 get(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(window)

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


bool makeScreenshot(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.


© 2019 Luxoft Sweden AB. 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.