WindowManager QML Type
The window model and controller. More...
Import Statement: | import QtApplicationManager.SystemUI |
Properties
- count : int
- runningOnDesktop : bool
- slowAnimations : bool
Signals
- raiseApplicationWindow(string applicationId)
- windowAboutToBeRemoved(WindowObject window)
- windowAdded(WindowObject window)
- windowContentStateChanged(WindowObject window)
- windowPropertyChanged(WindowObject window, string name, var value)
Methods
- object addExtension(Component component)
- object get(int index)
- int indexOfWindow(WindowObject window)
- bool makeScreenshot(string filename, string selector)
- WindowObject window(int index)
- list<WindowObject> windowsOfApplication(string applicationId)
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 name | Type | Description |
---|---|---|
applicationId | string | The 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 | WindowObject | The WindowObject containing the client surface. To display it you have to put it in a WindowItem |
windowObject | WindowObject | Exactly 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. |
contentState | WindowObject::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 |
This property holds the number of applications available.
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.
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); } }
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.
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:
Format | Description |
---|---|
%s | Will be replaced with the screen-id of this particular screenshot. |
%i | Will 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.