WindowManager QML Type

The WindowManager singleton. More...

Import Statement: import QtApplicationManager 1.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.
windowItemItemThe QtQuick Item representing the window surface of the application - used to actually composite the window on the screen.
isFullscreenboolA boolean value indicating whether the surface is being displayed in fullscreen mode.
isMappedboolA boolean value indicating whether the surface is mapped (visible).
isClosingboolA boolean value indicating whether the surface is currently closing. A surface is closing when the wayland surface is already destroyed, but the window is still available for showing an animation until releaseWindow() is called.

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 windowReady signal. All those changes are not lost however, but the last change before emitting the windowReady 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.0
import QtApplicationManager 1.0

// Simple solution for a full-screen setup
Item {
    id: fullscreenView

    MouseArea {
        // Without this area, mouse events would propagate "through" the surfaces
        id: filterMouseEventsForWindowContainer
        anchors.fill: parent
        enabled: false
    }

    Item {
        id: windowContainer
        anchors.fill: parent
        state: "closed"

        function windowReadyHandler(index, window) {
            filterMouseEventsForWindowContainer.enabled = true
            windowContainer.state = ""
            windowContainer.windowItem = window
        }
        function windowClosingHandler(index, window) {
            if (window === windowContainer.windowItem) {
                // Start close animation
                windowContainer.state = "closed"
            } else {
                // Immediately close anything not handled by this container
                WindowManager.releasewindow(window)
            }
        }
        function windowLostHandler(index, window) {
            if (windowContainer.windowItem === window) {
                windowContainer.windowItem = placeHolder
            }
        }
        Component.onCompleted: {
            WindowManager.windowReady.connect(windowReadyHandler)
            WindowManager.windowClosing.connect(windowClosingHandler)
            WindowManager.windowLost.connect(windowLostHandler)
        }

        property Item windowItem: placeHolder
        onWindowItemChanged: {
            windowItem.parent = windowContainer  // Always reset parent
        }

        Item {
            id: placeHolder;
        }

        // Use a different syntax for 'anchors.fill: parent' due to the volatile nature of windowItem
        Binding { target: windowContainer.windowItem; property: "x"; value: windowContainer.x }
        Binding { target: windowContainer.windowItem; property: "y"; value: windowContainer.y }
        Binding { target: windowContainer.windowItem; property: "width"; value: windowContainer.width }
        Binding { target: windowContainer.windowItem; property: "height"; value: windowContainer.height }

        transitions: [
            Transition {
                to: "closed"
                SequentialAnimation {
                    alwaysRunToEnd: true

                    // Closing animation declared here
                    // ...

                    ScriptAction {
                        script: {
                            windowContainer.windowItem.visible = false;
                            WindowManager.releaseWindow(windowContainer.windowItem);
                            filterMouseEventsForWindowContainer.enabled = false;
                        }
                    }
                }
            },
            Transition {
                from: "closed"
                SequentialAnimation {
                    alwaysRunToEnd: true

                    // Opening animation declared here
                    // ...
                }
            }
        ]
    }
}

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(string applicationId)

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


windowClosing(int index, Item window)

This signal is emitted when a window surface is unmapped.

For the convenience of the System-UI, this signal will provide you with both the QML window Item as well as the index of that window within the WindowManager model.

Either the client application closed the window, or it exited and all its Wayland surfaces got implicitly unmapped. When using the qml-inprocess runtime, this signal is also emitted when the close signal of the fake surface is triggered.

The actual surface can still be used for animations as it is not deleted immediately after this signal is emitted.

More information about this window can be retrieved via the model index.

See also windowLost().


windowLost(int index, Item window)

This signal is emitted when the window surface has been destroyed on the client side.

For the convenience of the System-UI, this signal will provide you with both the QML window Item as well as the index of that window within the WindowManager model.

If the surface was mapped, you will receive an implicit windowClosing signal before windowLost.

Note: It is mandatory to call releaseWindow() after the windowLost() signal has been received: all resources associated with the window surface will not be released automatically. The timing is up to the System-UI; calling releaseWindow() can be delayed in order to play a shutdown animation, but failing to call it will result in resource leaks.

Note: If the System-UI fails to call releaseWindow() within 2 seconds afer receiving the windowLost() signal, the application-manager will automatically call it to prevent resource leaks and deadlocks on shutdown.

More information about this window can be retrieved via the model index.


windowPropertyChanged(Item 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.

See also ApplicationManagerWindow::setWindowProperty().


windowReady(int index, Item window)

This signal is emitted after a new window surface has been created. Most likely due to an application launch.

For the convenience of the System-UI, this signal will provide you with both the QML window Item as well as the index of that window within the WindowManager model.

More information about this window can be retrieved via the model index. Most often you need the owning application of the window, which can be achieved by:

var appId = WindowManager.get(index).applicationId
var app = ApplicationManager.application(appId)

Note: Please be aware that the windowReady 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.


Method Documentation

object get(int index) const

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(Item 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.


registerCompositorView(QQuickWindow *view)

Registers the given view as a possible destination for Wayland window composition.

Wayland window items can only be rendered within top-level windows that have been registered via this function.

Note: The view parameter is an actual top-level window on the server side - not a client application window item.


releaseWindow(Item window)

Releases all resources of the window surface and removes the window from the model.

Note: It is mandatory to call this function after the windowLost() signal has been received: all resources associated with the window surface will not be released automatically. The timing is up to the System-UI; calling releaseWindow() can be delayed in order to play a shutdown animation, but failing to call it will result in resource leaks.

Note: If the System-UI fails to call releaseWindow() within 2 seconds afer receiving the windowLost() signal, the application-manager will automatically call it to prevent resource leaks and deadlocks on shutdown.

See also windowLost.


bool setWindowProperty(Item window, string name, var value)

Sets an application window's shared property identified by name to the given value.

These properties are shared between the System-UI and the client application: in single-process mode simply via a QVariantMap; in multi-process mode the sharing is done via Qt's extended surface Wayland extension. Changes from the client side are notified by the windowPropertyChanged() signal.

See ApplicationManagerWindow for the client side API.

See also windowProperty(), windowProperties(), and windowPropertyChanged().


var windowProperties(Item window)

Returns an object containing all shared properties of an application window.

See also setWindowProperty().


var windowProperty(Item window, string name)

Returns the value of an application window's shared property identified by name.

See also setWindowProperty().


© 2018 Pelagicore AG. 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.