Development/Tutorials/KWin/Scripting/API 4.9

Workspace

Workspace is the global object injected into each script as workspace. It provides access to core functionality of the window manager.

Read-only Properties

• QSize desktopGridSize
• int desktopGridWidth
• int desktopGridHeight
• int workspaceWidth
• int workspaceHeight
• QSize workspaceSize
• QSize displaySize: The same of the display, that is all screens.
• int displayWidth: The width of the display, that is width of all combined screens.
• int displayHeight: The height of the display, that is height of all combined screens.
• int activeScreen
• int numScreens

Read-write Properties

• int currentDesktop
• KWin::Client activeClient
• int desktops: The number of desktops currently used. Minimum number of desktops is 1, maximum 20.

Signals

• desktopPresenceChanged(KWin::Client *, int)
• currentDesktopChanged(int)
• clientAdded(KWin::Client *)
• clientRemoved(KWin::Client *)
• clientManaging(KWin::Client *)
• clientMinimized(KWin::Client *)
• clientUnminimized(KWin::Client *)
• clientRestored(KWin::Client *)
• clientMaximizeSet(KWin::Client *, bool, bool)
• killWindowCalled(KWin::Client *)
• clientActivated(KWin::Client *)
• clientFullScreenSet(KWin::Client *, bool, bool)
• clientSetKeepAbove(KWin::Client *, bool)
• numberDesktopsChanged(int oldNumberOfDesktops): Signal emitted whenever the number of desktops changed. To get the current number of desktops use the property desktops. oldNumberOfDesktops The previous number of desktops.

Functions

• slotSwitchDesktopNext()
• slotSwitchDesktopPrevious()
• slotSwitchDesktopRight()
• slotSwitchDesktopLeft()
• slotSwitchDesktopUp()
• slotSwitchDesktopDown()
• slotSwitchToNextScreen()
• slotWindowToNextScreen()
• slotToggleShowDesktop()
• slotWindowMaximize()
• slotWindowMaximizeVertical()
• slotWindowMaximizeHorizontal()
• slotWindowMinimize()
• slotWindowShade()
• slotWindowRaise()
• slotWindowLower()
• slotWindowRaiseOrLower()
• slotActivateAttentionWindow()
• slotWindowPackLeft()
• slotWindowPackRight()
• slotWindowPackUp()
• slotWindowPackDown()
• slotWindowGrowHorizontal()
• slotWindowGrowVertical()
• slotWindowShrinkHorizontal()
• slotWindowShrinkVertical()
• slotWindowQuickTileLeft()
• slotWindowQuickTileRight()
• slotWindowQuickTileTopLeft()
• slotWindowQuickTileTopRight()
• slotWindowQuickTileBottomLeft()
• slotWindowQuickTileBottomRight()
• slotSwitchWindowUp()
• slotSwitchWindowDown()
• slotSwitchWindowRight()
• slotSwitchWindowLeft()
• slotIncreaseWindowOpacity()
• slotLowerWindowOpacity()
• slotWindowOperations()
• slotWindowClose()
• slotWindowMove()
• slotWindowResize()
• slotWindowAbove()
• slotWindowBelow()
• slotWindowOnAllDesktops()
• slotWindowFullScreen()
• slotWindowNoBorder()
• slotWindowToNextDesktop()
• slotWindowToPreviousDesktop()
• slotWindowToDesktopRight()
• slotWindowToDesktopLeft()
• slotWindowToDesktopUp()
• slotWindowToDesktopDown()
• Q_INVOKABLE QList< KWin::Client * > clientList() const
• QRect clientArea(ClientAreaOption option, int screen, int desktop) const : Returns the geometry a Client can use with the specified option. This method should be preferred over other methods providing screen sizes as the various options take constraints such as struts set on panels into account. This method is also multi screen aware, but there are also options to get full areas. option The type of area which should be considered screen The screen for which the area should be considered desktop The desktop for which the area should be considered, in general there should not be a difference The specified screen geometry
• QRect clientArea(ClientAreaOption option, const QPoint &point, int desktop) const : Overloaded method for convenience. option The type of area which should be considered point The coordinates which have to be included in the area desktop The desktop for which the area should be considered, in general there should not be a difference The specified screen geometry
• QRect clientArea(ClientAreaOption option, const Client *client) const : Overloaded method for convenience. client The Client for which the area should be retrieved The specified screen geometry
• QString desktopName(int desktop) const : Returns the name for the given desktop.
• QString supportInformation() const : Provides support information about the currently running KWin instance.

KWin::Toplevel

Toplevel is an abstract base class for all "Windows". You cannot use it directly, but everything available on Toplevel is available on Client, too.

Read-only Properties

• bool alpha
• qulonglong frameId
• QRect geometry
• int height
• QPoint pos
• int screen
• QSize size
• int width
• qulonglong windowId
• int x
• int y
• int desktop
• QRect rect
• QPoint clientPos
• QSize clientSize
• QByteArray resourceName
• QByteArray resourceClass
• QByteArray windowRole
• bool desktopWindow: Returns whether the window is a desktop background window (the one with wallpaper). See _NET_WM_WINDOW_TYPE_DESKTOP at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dock: Returns whether the window is a dock (i.e. a panel). See _NET_WM_WINDOW_TYPE_DOCK at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool toolbar: Returns whether the window is a standalone (detached) toolbar window. See _NET_WM_WINDOW_TYPE_TOOLBAR at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool menu: Returns whether the window is a torn-off menu. See _NET_WM_WINDOW_TYPE_MENU at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool normalWindow: Returns whether the window is a "normal" window, i.e. an application or any other window for which none of the specialized window types fit. See _NET_WM_WINDOW_TYPE_NORMAL at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dialog: Returns whether the window is a dialog window. See _NET_WM_WINDOW_TYPE_DIALOG at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool splash: Returns whether the window is a splashscreen. Note that many (especially older) applications do not support marking their splash windows with this type. See _NET_WM_WINDOW_TYPE_SPLASH at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool utility: Returns whether the window is a utility window, such as a tool window. See _NET_WM_WINDOW_TYPE_UTILITY at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dropdownMenu: Returns whether the window is a dropdown menu (i.e. a popup directly or indirectly open from the applications menubar). See _NET_WM_WINDOW_TYPE_DROPDOWN_MENU at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool popupMenu: Returns whether the window is a popup menu (that is not a torn-off or dropdown menu). See _NET_WM_WINDOW_TYPE_POPUP_MENU at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool tooltip: Returns whether the window is a tooltip. See _NET_WM_WINDOW_TYPE_TOOLTIP at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool notification: Returns whether the window is a window with a notification. See _NET_WM_WINDOW_TYPE_NOTIFICATION at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool comboBox: Returns whether the window is a combobox popup. See _NET_WM_WINDOW_TYPE_COMBO at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dndIcon: Returns whether the window is a Drag&Drop icon. See _NET_WM_WINDOW_TYPE_DND at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• int windowType: Returns the NETWM window type See http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• QStringList activities
• bool managed: Whether this Toplevel is managed by KWin (it has control over its placement and other aspects, as opposed to override-redirect windows that are entirely handled by the application).
• bool deleted: Whether this Toplevel represents an already deleted window and only kept for the compositor for animations.
• bool shaped: Whether the window has an own shape

Read-write Properties

• qreal opacity

Signals

• opacityChanged(KWin::Toplevel *toplevel, qreal oldOpacity)
• damaged(KWin::Toplevel *toplevel, const QRect &damage)
• propertyNotify(KWin::Toplevel *toplevel, long a)
• geometryChanged()
• geometryShapeChanged(KWin::Toplevel *toplevel, const QRect &old)
• windowClosed(KWin::Toplevel *toplevel, KWin::Deleted *deleted)
• windowShown(KWin::Toplevel *toplevel)
• shapedChanged(): Signal emitted when the window's shape state changed. That is if it did not have a shape and received one or if the shape was withdrawn. Think of Chromium enabling/disabling KWin's decoration.

Functions

• Q_INVOKABLE void addRepaint(const QRect &r)
• Q_INVOKABLE void addRepaint(const QRegion &r)
• Q_INVOKABLE void addRepaint(int x, int y, int w, int h)
• Q_INVOKABLE void addLayerRepaint(const QRect &r)
• Q_INVOKABLE void addLayerRepaint(const QRegion &r)
• Q_INVOKABLE void addLayerRepaint(int x, int y, int w, int h)
• Q_INVOKABLE void addRepaintFull()

KWin::Client

The Client class encapsulates a window decoration frame. Inherits: KWin::Toplevel

Read-only Properties

• bool active: Whether this Client is active or not. Use Workspace::activateClient() to activate a Client. Workspace::activateClient
• QString caption: The Caption of the Client. Read from WM_NAME property together with a suffix for hostname and shortcut. To read only the caption as provided by WM_NAME, use the getter with an additional false value.
• bool closeable: Whether the window can be closed by the user. The value is evaluated each time the getter is called. Because of that no changed signal is provided.
• bool fullScreenable: Whether the Client can be set to fullScreen. The property is evaluated each time it is invoked. Because of that there is no notify signal.
• bool maximizable: Whether the Client can be maximized both horizontally and vertically. The property is evaluated each time it is invoked. Because of that there is no notify signal.
• bool minimizable: Whether the Client can be minimized. The property is evaluated each time it is invoked. Because of that there is no notify signal.
• bool modal: Whether the Client represents a modal window.
• bool moveable: Whether the Client is moveable. Even if it is not moveable, it might be possible to move it to another screen. The property is evaluated each time it is invoked. Because of that there is no notify signal. moveableAcrossScreens
• bool moveableAcrossScreens: Whether the Client can be moved to another screen. The property is evaluated each time it is invoked. Because of that there is no notify signal. moveable
• bool providesContextHelp: Whether the Client provides context help. Mostly needed by decorations to decide whether to show the help button or not.Returns whether the window provides context help or not. If it does, you should show a help menu item or a help button like '?' and call contextHelp() if this is invoked.contextHelp()
• bool resizeable: Whether the Client can be resized. The property is evaluated each time it is invoked. Because of that there is no notify signal.
• bool shadeable: Whether the Client can be shaded. The property is evaluated each time it is invoked. Because of that there is no notify signal.
• bool transient: Whether the Client is a transient Window to another Window. transientFor
• KWin::Client transientFor: The Client to which this Client is a transient if any.
• QSize basicUnit: By how much the window wishes to grow/shrink at least. Usually QSize(1,1). MAY BE DISOBEYED BY THE WM! It's only for information, do NOT rely on it at all. The value is evaluated each time the getter is called. Because of that no changed signal is provided.
• bool move: Whether the Client is currently being moved by the user. Notify signal is emitted when the Client starts or ends move/resize mode.
• bool resize: Whether the Client is currently being resized by the user. Notify signal is emitted when the Client starts or ends move/resize mode.
• QRect iconGeometry: The optional geometry representing the minimized Client in e.g a taskbar. See _NET_WM_ICON_GEOMETRY at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html . The value is evaluated each time the getter is called. Because of that no changed signal is provided.
• bool specialWindow: Returns whether the window is any of special windows types (desktop, dock, splash, ...), i.e. window types that usually don't have a window frame and the user does not use window management (moving, raising,...) on them. The value is evaluated each time the getter is called. Because of that no changed signal is provided.
• bool wantsInput: Whether the Client can accept keyboard focus. The value is evaluated each time the getter is called. Because of that no changed signal is provided.
• QPixmap icon
• KWin::TabGroup tabGroup: The "Window Tabs" Group this Client belongs to.
• bool isCurrentTab: Whether this Client is the currently visible Client in its Client Group (Window Tabs). For change connect to the visibleChanged signal on the Client's Group.
• QSize minSize: Minimum size as specified in WM_NORMAL_HINTS
• QSize maxSize: Maximum size as specified in WM_NORMAL_HINTS

Read-write Properties

• int desktop: The desktop this Client is on. If the Client is on all desktops the property has value -1.Returns the virtual desktop within the workspace() the client window is located in, 0 if it isn't located on any special desktop (not mapped yet), or NET::OnAllDesktops. Do not use desktop() directly, use isOnDesktop() instead.
• bool fullScreen: Whether this Client is fullScreen. A Client might either be fullScreen due to the _NET_WM property or through a legacy support hack. The fullScreen state can only be changed if the Client does not use the legacy hack. To be sure whether the state changed, connect to the notify signal.
• QRect geometry: The geometry of this Client. Be aware that depending on resize mode the geometryChanged signal might be emitted at each resize step or only at the end of the resize operation.
• bool keepAbove: Whether the Client is set to be kept above other windows.
• bool keepBelow: Whether the Client is set to be kept below other windows.
• bool minimized: Whether the Client is minimized.
• bool shade: Whether the Client is shaded.
• bool skipSwitcher: Whether the Client should be excluded from window switching effects.
• bool skipTaskbar: Indicates that the window should not be included on a taskbar.
• bool skipPager: Indicates that the window should not be included on a Pager.
• bool noBorder: Whether the window has a decoration or not. This property is not allowed to be set by applications themselves. The decision whether a window has a border or not belongs to the window manager. If this property gets abused by application developers, it will be removed again.

Signals

• clientManaging(KWin::Client *)
• clientFullScreenSet(KWin::Client *, bool, bool)
• clientMaximizedStateChanged(KWin::Client *, KDecorationDefines::MaximizeMode)
• clientMaximizedStateChanged(KWin::Client *c, bool h, bool v)
• clientMinimized(KWin::Client *client, bool animate)
• clientUnminimized(KWin::Client *client, bool animate)
• clientStartUserMovedResized(KWin::Client *)
• clientStepUserMovedResized(KWin::Client *, const QRect &)
• clientFinishUserMovedResized(KWin::Client *)
• activeChanged()
• captionChanged()
• desktopChanged()
• fullScreenChanged()
• transientChanged()
• modalChanged()
• shadeChanged()
• keepAboveChanged()
• keepBelowChanged()
• minimizedChanged()
• moveResizedChanged()
• iconChanged()
• skipSwitcherChanged()
• skipTaskbarChanged()
• skipPagerChanged()
• tabGroupChanged(): Emitted whenever the Client's TabGroup changed. That is whenever the Client is moved to another group, but not when a Client gets added or removed to the Client's ClientGroup.

Functions

• closeWindow(): Closes the window by either sending a delete_window message or using XKill.
• Q_INVOKABLE bool tabBefore(Client *other, bool activate)
• Q_INVOKABLE bool tabBehind(Client *other, bool activate)
• Q_INVOKABLE bool untab(const QRect &toGeometry=QRect())

KWin::ClientGroup

Read-only Properties

• QSize minSize: Combined minimum size of all clients in the group.
• QSize maxSize: Combined maximum size of all clients in the group.
• int visibleClientIndex: The index of the visible Client in this group.
• QList<KWin::Client*> clients: The Clients in this group.

Read-write Properties

• KWin::Client visible: Currently visible client in this group.

Signals

• visibleChanged(): Emitted when the visible Client in this group changes.
• minSizeChanged(): Emitted when the group's minimum size changes.
• maxSizeChanged(): Emitted when the group's maximum size changes.

Functions

• add(KWin::Client *c, int before=-1, bool becomeVisible=false): Adds c to the group before before in the list. If becomeVisible is true then the added client will become also the visible client.
• remove(int index, const QRect &newGeom=QRect(), bool toNullGroup=false): Remove the client at index index from the group. If newGeom is set then the client will move and resize to the specified geometry, otherwise it will stay where the group is located. If toNullGroup is not true then the client will be added to a new group of its own.
• remove(KWin::Client *c, const QRect &newGeom=QRect(), bool toNullGroup=false): Remove c from the group. If newGeom is set then the client will move and resize to the specified geometry, otherwise it will stay where the group is located. If toNullGroup is not true then the client will be added to a new group of its own.
• removeAll(): Remove all clients from this group. Results in all clients except the first being moved to a group of their own.
• closeAll(): Close all clients in this group.
• move(int index, int before): Move the client at index index to the position before the client at index before in the list.
• move(KWin::Client *c, KWin::Client *before): Move c to the position before before in the list.
• displayClientMenu(int index, const QPoint &pos): Display the right-click client menu belonging to the client at index index at the global coordinates specified by pos.
• displayClientMenu(KWin::Client *c, const QPoint &pos): Display the right-click client menu belonging to c at the global coordinates specified by pos.
• int indexOfClient(KWin::Client *c): Returns the list index of c.
• bool contains(KWin::Client *c): Returns whether or not this group contains c.