Development/Tutorials/KWin/Scripting/API: Difference between revisions

From KDE TechBase
(add warning that the API will change)
(Update to 5.21 API)
Line 1: Line 1:
{{warning|The API documented here is only valid till 4.8. The new API is documented in [[Development/Tutorials/KWin/Scripting/API_4.9|Scripting API 4.9]]. Explicit changes are documented in [[Projects/KWin/Scripting_Update_Notes|Scripting Update Notes]].}}
This page describes the KWin Scripting API as of KWin 5.21. It has been generated using https://invent.kde.org/nicolasfella/kwin-scripting-api-generator


= workspace[singleton] =
== Global ==
== Events ==
Methods and properties added to the global JavaScript object.
'''workspace.currentDesktopChanged'''
=== Read-only Properties ===
*Emitted when the user switches from a virtual desktop to another.
 
**'''old_desk {integer}''': The number of the virtual desktop the user switched from.
* ''KWin::Options'' '''options''': Global property to all configuration values of KWin core.
* ''KWin::Workspace'' '''workspace''': Global property to the core wrapper of KWin.
* ''object'' '''KWin''': Provides access to enums defined in KWin::WorkspaceWrapper
=== Functions ===
 
* '''print(QVariant ... values)''': Prints all provided values to kDebug and as a D-Bus signal
* ''QVariant'' '''readConfig(QString key, QVariant defaultValue = QVariant())''': Reads the config value for key in the Script's configuration with the optional default value. If not providing a default value and no value stored in the configuration an undefined value is returned.
* ''bool'' '''registerScreenEdge(ElectricBorder border, QScriptValue callback)''': Registers the callback for the screen edge. When the mouse gets pushed against the given edge the callback will be invoked. Scripts can also add "X-KWin-Border-Activate" to their metadata file to have the effect listed in the screen edges KCM. This will write an entry BorderConfig= in the script configuration object with a list of ScreenEdges the user has selected.
* ''bool'' '''unregisterScreenEdge(ElectricBorder border)''': Unregisters the callback for the screen edge. This will disconnect all callbacks from this script to that edge.
* ''bool'' '''registerShortcut(QString title, QString text, QString keySequence, QScriptValue callback)''': Registers keySequence as a global shortcut. When the shortcut is invoked the callback will be called. Title and text are used to name the shortcut and make it available to the global shortcut configuration module.
* ''bool'' '''assert(bool value, QString message = QString())''': Aborts the execution of the script if value does not evaluate to true. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
* ''bool'' '''assertTrue(bool value, QString message = QString())''': Aborts the execution of the script if value does not evaluate to true. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
* ''bool'' '''assertFalse(bool value, QString message = QString())''': Aborts the execution of the script if value does not evaluate to false. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
* ''bool'' '''assertEquals(QVariant expected, QVariant actual, QString message = QString())''': Aborts the execution of the script if the actual value is not equal to the expected value. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
* ''bool'' '''assertNull(QVariant value, QString message = QString())''': Aborts the execution of the script if value is not null. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
* ''bool'' '''assertNotNull(QVariant value, QString message = QString())''': Aborts the execution of the script if value is null. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
* '''callDBus(QString service, QString path, QString interface, QString method, QVariant arg..., QScriptValue callback = QScriptValue())''': Call a D-Bus method at (service, path, interface and method). A variable number of arguments can be added to the method call. The D-Bus call is always performed in an async way invoking the callback provided as the last (optional) argument. The reply values of the D-Bus method call are passed to the callback.
* '''registerUserActionsMenu(QScriptValue callback)''': Registers the passed in callback to be invoked whenever the User actions menu (Alt+F3 or right click on window decoration) is about to be shown. The callback is invoked with a reference to the Client for which the menu is shown. The callback can return either a single menu entry to be added to the menu or an own sub menu with multiple entries. The object for a menu entry should be {title: "My Menu entry", checkable: true, checked: false, triggered: function (action) { // callback with triggered QAction}}, for a menu it should be {title: "My menu", items: [{...}, {...}, ...] /*list with entries as described*/}


 
== KWin::WorkspaceWrapper ==


'''workspace.desktopPresenceChanged'''
=== Enums ===
*Emitted whenever a client is moved across virtual desktops. The client's previous desktop is available through the old_desk parameter, whereas the current desktop can be fetched using moved_client.desktop
 
**'''moved_client {client}''': The client which was moved from desktop old_desk to the new one
==== ClientAreaOption ====
**'''old_desk {integer}''': The previous desktop on which the client was present
   
* '''PlacementArea''': window movement snapping area? ignore struts
* '''MovementArea''':
* '''MaximizeArea''':
* '''MaximizeFullArea''':
* '''FullScreenArea''':
* '''WorkArea''':
* '''FullArea''':
* '''ScreenArea''':
==== ElectricBorder ====
   
* '''ElectricTop''':
* '''ElectricTopRight''':
* '''ElectricRight''':
* '''ElectricBottomRight''':
* '''ElectricBottom''':
* '''ElectricBottomLeft''':
* '''ElectricLeft''':
* '''ElectricTopLeft''':
* '''ELECTRIC_COUNT''':
* '''ElectricNone''':
=== 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. Deprecatedsince 5.0 use virtualScreenSize
* ''int'' '''displayWidth''': The width of the display, that is width of all combined screens. Deprecatedsince 5.0 use virtualScreenSize
* ''int'' '''displayHeight''': The height of the display, that is height of all combined screens. Deprecatedsince 5.0 use virtualScreenSize
* ''int'' '''activeScreen'''
* ''int'' '''numScreens'''
* ''QStringList'' '''activities'''
* ''QSize'' '''virtualScreenSize''': The bounding size of all screens combined. Overlapping areas are not counted multiple times. virtualScreenGeometry
* ''QRect'' '''virtualScreenGeometry''': The bounding geometry of all outputs combined. Always starts at (0,0) and has virtualScreenSize as it's size. virtualScreenSize
=== Read-write Properties ===
 
* ''int'' '''currentDesktop'''
* ''KWin::AbstractClient *'' '''activeClient'''
* ''int'' '''desktops''': The number of desktops currently used. Minimum number of desktops is 1, maximum 20.
* ''QString'' '''currentActivity'''
=== Signals ===
 
* '''desktopPresenceChanged(KWin::AbstractClient *client, int desktop)'''
* '''currentDesktopChanged(int desktop, KWin::AbstractClient *client)'''
* '''clientAdded(KWin::AbstractClient *client)'''
* '''clientRemoved(KWin::AbstractClient *client)'''
* '''clientManaging(KWin::X11Client *client)'''
* '''clientMinimized(KWin::AbstractClient *client)'''
* '''clientUnminimized(KWin::AbstractClient *client)'''
* '''clientRestored(KWin::X11Client *client)'''
* '''clientMaximizeSet(KWin::AbstractClient *client, bool h, bool v)'''
* '''killWindowCalled(KWin::X11Client *client)'''
* '''clientActivated(KWin::AbstractClient *client)'''
* '''clientFullScreenSet(KWin::X11Client *client, bool fullScreen, bool user)'''
* '''clientSetKeepAbove(KWin::X11Client *client, bool keepAbove)'''
* '''numberDesktopsChanged(uint 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.
* '''desktopLayoutChanged()''': Signal emitted whenever the layout of virtual desktops changed. That is desktopGrid(Size/Width/Height) will have new values. 4.11
* '''clientDemandsAttentionChanged(KWin::AbstractClient *client, bool set)''': The demands attention state for Client c changed to set. c The Client for which demands attention changed set New value of demands attention
* '''numberScreensChanged(int count)''': Signal emitted when the number of screens changes. count The new number of screens
* '''screenResized(int screen)''': This signal is emitted when the size of screen changes. Don't forget to fetch an updated client area.
* '''currentActivityChanged(const QString &id)''': Signal emitted whenever the current activity changed. id id of the new activity
* '''activitiesChanged(const QString &id)''': Signal emitted whenever the list of activities changed. id id of the new activity
* '''activityAdded(const QString &id)''': This signal is emitted when a new activity is added id id of the new activity
* '''activityRemoved(const QString &id)''': This signal is emitted when the activity is removed id id of the removed activity
* '''virtualScreenSizeChanged()''': Emitted whenever the virtualScreenSize changes. virtualScreenSize() 5.0
* '''virtualScreenGeometryChanged()''': Emitted whenever the virtualScreenGeometry changes. virtualScreenGeometry() 5.0
=== 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()'''
* '''slotWindowQuickTileTop()'''
* '''slotWindowQuickTileBottom()'''
* '''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()'''
* '''sendClientToScreen(KWin::AbstractClient *client, int screen)''': Sends the AbstractClient to the given screen.
* '''showOutline(const QRect &geometry)''': Shows an outline at the specified geometry. If an outline is already shown the outline is moved to the new position. Use hideOutline to remove the outline again.
* '''showOutline(int x, int y, int width, int height)''': Overloaded method for convenience.
* '''hideOutline()''': Hides the outline previously shown by showOutline.
* ''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 KWin::AbstractClient *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.
* '''createDesktop(int position, const QString &name) const''': Create a new virtual desktop at the requested position. position The position of the desktop. It should be in range [0, count]. name The name for the new desktop, if empty the default name will be used.
* '''removeDesktop(int position) const''': Remove the virtual desktop at the requested position position The position of the desktop to be removed. It should be in range [0, count - 1].
* ''QString'' '''supportInformation() const''': Provides support information about the currently running KWin instance.
* ''KWin::X11Client *'' '''getClient(qulonglong windowId)''': Finds the Client with the given windowId. windowId The window Id of the Client The found Client or null


 
== KWin::Options ==


'''workspace.clientAdded'''
=== Enums ===
*Emitted whenever a new client is added to the workspace. This generally occurs when a new window is opened which includes dialog boxes, windows etc. However, it is NOT emitted for unmanaged clients like the Alt+Tab switcher.
 
**'''added_client {client}''': The client which was added.
==== FocusPolicy ====
   
* '''ClickToFocus''': Clicking into a window activates it. This is also the default.
* '''FocusFollowsMouse''': Moving the mouse pointer actively onto a normal window activates it. For convenience, the desktop and windows on the dock are excluded. They require clicking.
* '''FocusUnderMouse''': The window that happens to be under the mouse pointer becomes active. The invariant is: no window can have focus that is not under the mouse. This also means that Alt-Tab won't work properly and popup dialogs are usually unsable with the keyboard. Note that the desktop and windows on the dock are excluded for convenience. They get focus only when clicking on it.
* '''FocusStrictlyUnderMouse''': This is even worse than FocusUnderMouse. Only the window under the mouse pointer is active. If the mouse points nowhere, nothing has the focus. If the mouse points onto the desktop, the desktop has focus. The same holds for windows on the dock.
==== WindowOperation ====
   
* '''MaximizeOp''':
* '''RestoreOp''':
* '''MinimizeOp''':
* '''MoveOp''':
* '''UnrestrictedMoveOp''':
* '''ResizeOp''':
* '''UnrestrictedResizeOp''':
* '''CloseOp''':
* '''OnAllDesktopsOp''':
* '''ShadeOp''':
* '''KeepAboveOp''':
* '''KeepBelowOp''':
* '''OperationsOp''':
* '''WindowRulesOp''':
* '''ToggleStoreSettingsOp''':
* '''HMaximizeOp''':
* '''VMaximizeOp''':
* '''LowerOp''':
* '''FullScreenOp''':
* '''NoBorderOp''':
* '''NoOp''':
* '''SetupWindowShortcutOp''':
* '''ApplicationRulesOp''':
==== MouseCommand ====
   
* '''MouseRaise''':
* '''MouseLower''':
* '''MouseOperationsMenu''':
* '''MouseToggleRaiseAndLower''':
* '''MouseActivateAndRaise''':
* '''MouseActivateAndLower''':
* '''MouseActivate''':
* '''MouseActivateRaiseAndPassClick''':
* '''MouseActivateAndPassClick''':
* '''MouseMove''':
* '''MouseUnrestrictedMove''':
* '''MouseActivateRaiseAndMove''':
* '''MouseActivateRaiseAndUnrestrictedMove''':
* '''MouseResize''':
* '''MouseUnrestrictedResize''':
* '''MouseShade''':
* '''MouseSetShade''':
* '''MouseUnsetShade''':
* '''MouseMaximize''':
* '''MouseRestore''':
* '''MouseMinimize''':
* '''MouseNextDesktop''':
* '''MousePreviousDesktop''':
* '''MouseAbove''':
* '''MouseBelow''':
* '''MouseOpacityMore''':
* '''MouseOpacityLess''':
* '''MouseClose''':
* '''MouseNothing''':
==== MouseWheelCommand ====
   
* '''MouseWheelRaiseLower''':
* '''MouseWheelShadeUnshade''':
* '''MouseWheelMaximizeRestore''':
* '''MouseWheelAboveBelow''':
* '''MouseWheelPreviousNextDesktop''':
* '''MouseWheelChangeOpacity''':
* '''MouseWheelNothing''':
==== GlSwapStrategy ====
   
* '''CopyFrontBuffer''':
* '''PaintFullScreen''':
* '''ExtendDamage''':
* '''AutoSwapStrategy''':
=== Read-only Properties ===
 
* ''bool'' '''focusPolicyIsReasonable'''
=== Read-write Properties ===
 
* ''FocusPolicy'' '''focusPolicy'''
* ''XwaylandCrashPolicy'' '''xwaylandCrashPolicy'''
* ''int'' '''xwaylandMaxCrashCount'''
* ''bool'' '''nextFocusPrefersMouse'''
* ''bool'' '''clickRaise''': Whether clicking on a window raises it in FocusFollowsMouse mode or not.
* ''bool'' '''autoRaise''': Whether autoraise is enabled FocusFollowsMouse mode or not.
* ''int'' '''autoRaiseInterval''': Autoraise interval.
* ''int'' '''delayFocusInterval''': Delayed focus interval.
* ''bool'' '''shadeHover''': Whether shade hover is enabled or not.
* ''int'' '''shadeHoverInterval''': Shade hover interval.
* ''bool'' '''separateScreenFocus''': Whether to see Xinerama screens separately for focus (in Alt+Tab, when activating next client)
* ''int'' '''placement'''
* ''int'' '''borderSnapZone''': The size of the zone that triggers snapping on desktop borders.
* ''int'' '''windowSnapZone''': The size of the zone that triggers snapping with other windows.
* ''int'' '''centerSnapZone''': The size of the zone that triggers snapping on the screen center.
* ''bool'' '''snapOnlyWhenOverlapping''': Snap only when windows will overlap.
* ''bool'' '''rollOverDesktops''': Whether or not we roll over to the other edge when switching desktops past the edge.
* ''int'' '''focusStealingPreventionLevel''': 0 - 4 , see Workspace::allowClientActivation()
* ''KWin::Options::WindowOperation'' '''operationTitlebarDblClick'''
* ''KWin::Options::WindowOperation'' '''operationMaxButtonLeftClick'''
* ''KWin::Options::WindowOperation'' '''operationMaxButtonMiddleClick'''
* ''KWin::Options::WindowOperation'' '''operationMaxButtonRightClick'''
* ''MouseCommand'' '''commandActiveTitlebar1'''
* ''MouseCommand'' '''commandActiveTitlebar2'''
* ''MouseCommand'' '''commandActiveTitlebar3'''
* ''MouseCommand'' '''commandInactiveTitlebar1'''
* ''MouseCommand'' '''commandInactiveTitlebar2'''
* ''MouseCommand'' '''commandInactiveTitlebar3'''
* ''MouseCommand'' '''commandWindow1'''
* ''MouseCommand'' '''commandWindow2'''
* ''MouseCommand'' '''commandWindow3'''
* ''MouseCommand'' '''commandWindowWheel'''
* ''MouseCommand'' '''commandAll1'''
* ''MouseCommand'' '''commandAll2'''
* ''MouseCommand'' '''commandAll3'''
* ''uint'' '''keyCmdAllModKey'''
* ''bool'' '''showGeometryTip''': Whether the Geometry Tip should be shown during a window move/resize.
* ''bool'' '''condensedTitle''': Whether the visible name should be condensed.
* ''bool'' '''electricBorderMaximize''': Whether a window gets maximized when it reaches top screen edge while being moved.
* ''bool'' '''electricBorderTiling''': Whether a window is tiled to half screen when reaching left or right screen edge while been moved.
* ''float'' '''electricBorderCornerRatio''': Whether a window is tiled to half screen when reaching left or right screen edge while been moved.
* ''bool'' '''borderlessMaximizedWindows'''
* ''int'' '''killPingTimeout''': timeout before non-responding application will be killed after attempt to close.
* ''bool'' '''hideUtilityWindowsForInactive''': Whether to hide utility windows for inactive applications.
* ''int'' '''compositingMode'''
* ''bool'' '''useCompositing'''
* ''int'' '''hiddenPreviews'''
* ''int'' '''glSmoothScale''': 0 = no, 1 = yes when transformed, 2 = try trilinear when transformed; else 1, -1 = auto
* ''bool'' '''xrenderSmoothScale'''
* ''bool'' '''glStrictBinding'''
* ''bool'' '''glStrictBindingFollowsDriver''': Whether strict binding follows the driver or has been overwritten by a user defined config value. If true glStrictBinding is set by the OpenGL Scene during initialization. If false glStrictBinding is set from a config value and not updated during scene initialization.
* ''bool'' '''glCoreProfile'''
* ''GlSwapStrategy'' '''glPreferBufferSwap'''
* ''KWin::OpenGLPlatformInterface'' '''glPlatformInterface'''
* ''bool'' '''windowsBlockCompositing'''
* ''LatencyPolicy'' '''latencyPolicy'''
* ''RenderTimeEstimator'' '''renderTimeEstimator'''
=== Signals ===
 
* '''focusPolicyChanged()'''
* '''focusPolicyIsResonableChanged()'''
* '''xwaylandCrashPolicyChanged()'''
* '''xwaylandMaxCrashCountChanged()'''
* '''nextFocusPrefersMouseChanged()'''
* '''clickRaiseChanged()'''
* '''autoRaiseChanged()'''
* '''autoRaiseIntervalChanged()'''
* '''delayFocusIntervalChanged()'''
* '''shadeHoverChanged()'''
* '''shadeHoverIntervalChanged()'''
* '''separateScreenFocusChanged(bool)'''
* '''placementChanged()'''
* '''borderSnapZoneChanged()'''
* '''windowSnapZoneChanged()'''
* '''centerSnapZoneChanged()'''
* '''snapOnlyWhenOverlappingChanged()'''
* '''rollOverDesktopsChanged(bool enabled)'''
* '''focusStealingPreventionLevelChanged()'''
* '''operationTitlebarDblClickChanged()'''
* '''operationMaxButtonLeftClickChanged()'''
* '''operationMaxButtonRightClickChanged()'''
* '''operationMaxButtonMiddleClickChanged()'''
* '''commandActiveTitlebar1Changed()'''
* '''commandActiveTitlebar2Changed()'''
* '''commandActiveTitlebar3Changed()'''
* '''commandInactiveTitlebar1Changed()'''
* '''commandInactiveTitlebar2Changed()'''
* '''commandInactiveTitlebar3Changed()'''
* '''commandWindow1Changed()'''
* '''commandWindow2Changed()'''
* '''commandWindow3Changed()'''
* '''commandWindowWheelChanged()'''
* '''commandAll1Changed()'''
* '''commandAll2Changed()'''
* '''commandAll3Changed()'''
* '''keyCmdAllModKeyChanged()'''
* '''showGeometryTipChanged()'''
* '''condensedTitleChanged()'''
* '''electricBorderMaximizeChanged()'''
* '''electricBorderTilingChanged()'''
* '''electricBorderCornerRatioChanged()'''
* '''borderlessMaximizedWindowsChanged()'''
* '''killPingTimeoutChanged()'''
* '''hideUtilityWindowsForInactiveChanged()'''
* '''compositingModeChanged()'''
* '''useCompositingChanged()'''
* '''hiddenPreviewsChanged()'''
* '''glSmoothScaleChanged()'''
* '''xrenderSmoothScaleChanged()'''
* '''glStrictBindingChanged()'''
* '''glStrictBindingFollowsDriverChanged()'''
* '''glCoreProfileChanged()'''
* '''glPreferBufferSwapChanged()'''
* '''glPlatformInterfaceChanged()'''
* '''windowsBlockCompositingChanged()'''
* '''animationSpeedChanged()'''
* '''latencyPolicyChanged()'''
* '''configChanged()'''
* '''renderTimeEstimatorChanged()'''
=== Functions ===
 


 
== KWin::Toplevel ==


'''workspace.clientManaging'''
=== Read-only Properties ===
*Emitted whenever a client is being managed by the KWin subsystem. The difference between workspace.clientManaging and workspace.clientAdded is that clientManaging is emitted BEFORE clientAdded. Also, if KWin is restarted with a list of clients C, then the clientManaging event will be emitted for every client in C, but clientAdded will not.
 
**'''managing_client {client}''': The client which is being managed.
* ''bool'' '''alpha'''
* ''qulonglong'' '''frameId'''
* ''QRect'' '''geometry''': This property holds the geometry of the Toplevel, excluding invisible portions, e.g. client-side and server-side drop-shadows, etc. DeprecatedUse frameGeometry property instead.
* ''QRect'' '''bufferGeometry''': This property holds rectangle that the pixmap or buffer of this Toplevel occupies on the screen. This rectangle includes invisible portions of the client, e.g. client-side drop shadows, etc.
* ''QRect'' '''frameGeometry''': This property holds the geometry of the Toplevel, excluding invisible portions, e.g. server-side and client-side drop-shadows, etc.
* ''QPoint'' '''pos''': This property holds the position of the Toplevel's frame geometry.
* ''QSize'' '''size''': This property holds the size of the Toplevel's frame geometry.
* ''int'' '''x''': This property holds the x position of the Toplevel's frame geometry.
* ''int'' '''y''': This property holds the y position of the Toplevel's frame geometry.
* ''int'' '''width''': This property holds the width of the Toplevel's frame geometry.
* ''int'' '''height''': This property holds the height of the Toplevel's frame geometry.
* ''QRect'' '''visibleRect'''
* ''int'' '''screen'''
* ''qulonglong'' '''windowId'''
* ''int'' '''desktop'''
* ''bool'' '''onAllDesktops''': Whether the window is on all desktops. That is desktop is -1.
* ''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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
* ''bool'' '''criticalNotification''': Returns whether the window is a window with a critical notification.
* ''bool'' '''onScreenDisplay''': Returns whether the window is an On Screen Display.
* ''bool'' '''comboBox''': Returns whether the window is a combobox popup. See _NET_WM_WINDOW_TYPE_COMBO at https://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 https://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
* ''int'' '''windowType''': Returns the NETWM window type See https://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
* ''quint32'' '''surfaceId''': The Id of the Wayland Surface associated with this Toplevel. On X11 only setups the value is 0.
* ''KWaylandServer::SurfaceInterface *'' '''surface''': Interface to the Wayland Surface. Relevant only in Wayland, in X11 it will be nullptr
* ''bool'' '''popupWindow''': Whether the window is a popup.
* ''bool'' '''outline''': Whether this Toplevel represents the outline. It's always false if compositing is turned off.
* ''QUuid'' '''internalId''': This property holds a UUID to uniquely identify this Toplevel.
* ''int'' '''pid''': The pid of the process owning this window. 5.20
=== Read-write Properties ===
 
* ''qreal'' '''opacity'''
* ''bool'' '''skipsCloseAnimation''': Whether the window does not want to be animated on window close. There are legit reasons for this like a screenshot application which does not want it's window being captured.
=== Signals ===
 
* '''opacityChanged(KWin::Toplevel *toplevel, qreal oldOpacity)'''
* '''damaged(KWin::Toplevel *toplevel, const QRegion &damage)'''
* '''inputTransformationChanged()'''
* '''geometryChanged()''': This signal is emitted when the Toplevel's frame geometry changes. Deprecatedsince 5.19, use frameGeometryChanged instead
* '''geometryShapeChanged(KWin::Toplevel *toplevel, const QRect &old)'''
* '''paddingChanged(KWin::Toplevel *toplevel, const QRect &old)'''
* '''windowClosed(KWin::Toplevel *toplevel, KWin::Deleted *deleted)'''
* '''windowShown(KWin::Toplevel *toplevel)'''
* '''windowHidden(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.
* '''screenChanged()''': Emitted whenever the Toplevel's screen changes. This can happen either in consequence to a screen being removed/added or if the Toplevel's geometry changes. 4.11
* '''skipCloseAnimationChanged()'''
* '''windowRoleChanged()''': Emitted whenever the window role of the window changes. 5.0
* '''windowClassChanged()''': Emitted whenever the window class name or resource name of the window changes. 5.0
* '''surfaceIdChanged(quint32)''': Emitted when a Wayland Surface gets associated with this Toplevel. 5.3
* '''hasAlphaChanged()''': 5.4
* '''surfaceChanged()''': Emitted whenever the Surface for this Toplevel changes.
* '''screenScaleChanged()'''
* '''shadowChanged()''': Emitted whenever the client's shadow changes. 5.15
* '''bufferGeometryChanged(KWin::Toplevel *toplevel, const QRect &oldGeometry)''': This signal is emitted when the Toplevel's buffer geometry changes.
* '''frameGeometryChanged(KWin::Toplevel *toplevel, const QRect &oldGeometry)''': This signal is emitted when the Toplevel's frame geometry changes.
* '''clientGeometryChanged(KWin::Toplevel *toplevel, const QRect &oldGeometry)''': This signal is emitted when the Toplevel's client geometry has changed.
=== Functions ===
 
* '''addRepaint(const QRect &r)'''
* '''addRepaint(const QRegion &r)'''
* '''addRepaint(int x, int y, int w, int h)'''
* '''addLayerRepaint(const QRect &r)'''
* '''addLayerRepaint(const QRegion &r)'''
* '''addLayerRepaint(int x, int y, int w, int h)'''
* '''addRepaintFull()'''


 
== KWin::AbstractClient ==


'''workspace.clientMinimized'''
=== Enums ===
*Emitted whenever a client is minimized.
 
**'''minimized_client {client}''': The client which was minimized.
==== Position ====
 
   
 
* '''PositionCenter''':
'''workspace.clientMaximizeSet'''
* '''PositionLeft''':
*Emitted whenever a client is maximized in a particular orientation. The orientation i.e. the rectangular direction in which the client was specified to occupy the entire available space is specified by the two parameters horizontally and vertically. If both are true, the client was maximized fully i.e. asked to occupy the entire workspace are available.
* '''PositionRight''':  
**'''maximized_client {client}''': The client which was maximized (in a certain orientation).
* '''PositionTop''':
**'''horizontally {boolean}''': (true) if the client was maximized horizontally, (false) otherwise.
* '''PositionBottom''':
**'''vertically {boolean}''': (true) if the client was maximized vertically, (false) otherwise.
* '''PositionTopLeft''':
 
* '''PositionTopRight''':
 
* '''PositionBottomLeft''':
'''workspace.killWindowCalled'''
* '''PositionBottomRight''':
*Emitted whenever the user requests a Kill Window [generally using the Ctrl+Esc combination]. The parameter killwindow_client is not completely safe and may return kill windows out of order of invocation. This is just a fancy function, avoid using. Instead, use workspace.clientAdded and filter for incoming Kill Windows.
==== ForceGeometry_t ====
**'''killwindow_client {client}''': The client handle to the kill window that was called.
   
 
* '''NormalGeometrySet''':  
 
* '''ForceGeometrySet''':  
'''workspace.clientActivated'''
==== SizeMode ====
*Emitted whenever a client is given focus or 'activated'.
   
**'''activated_client {client}''': The client which was activated (or received focus).
* '''SizeModeAny''':
 
* '''SizeModeFixedW''':  
 
* '''SizeModeFixedH''':
'''workspace.clientFullScreenSet'''
* '''SizeModeMax''':
*Emitted whenever a client is set to full screen or unset. The fss_set parameter can be used to determine whether the client was set or unset.
==== SameApplicationCheck ====
**'''fss_set {boolean}''': (true) if the client was switched to full screen mode, (false) if it was switched from full screen mode.
   
**'''fss_client {client}''': The client which was set/unset to fullscreen.
* '''RelaxedForActive''':  
 
* '''AllowCrossProcesses''':
 
=== Read-only Properties ===
'''workspace.clientUnminimized'''
 
*Emitted whenever a client is Unminimized (or restored).
* ''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.
**'''unm_client {client}''': The client which was unminimzed.
* ''bool'' '''active''': Whether this Client is active or not. Use Workspace::activateClient() to activate a Client. Workspace::activateClient
 
* ''QVector< uint >'' '''x11DesktopIds''': The x11 ids for all desktops this client is in. On X11 this list will always have a length of 1
== Methods ==
* ''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.
'''workspace.getAllClients[ret: Array(client)]'''
* ''QIcon'' '''icon'''
 
* ''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.
'''workspace.getAllClients(desktop_no {integer})'''
* ''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.
*Gets all clients on the virtual desktop desktop_no. If no desktop number is specified then it fetches all the clients. To specifically isolate clients which are on 'All desktops', set the desktop_no parameter to -1.
* ''QRect'' '''iconGeometry''': The optional geometry representing the minimized Client in e.g a taskbar. See _NET_WM_ICON_GEOMETRY at https://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.
*'''desktop_no {integer}''': The desktop number belonging to which the clients are to be fetched.
* ''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.
 
* ''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.
 
* ''QSize'' '''minSize''': Minimum size as specified in WM_NORMAL_HINTS
'''workspace.dimensions[ret: qsize]'''
* ''QSize'' '''maxSize''': Maximum size as specified in WM_NORMAL_HINTS
 
* ''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.
'''workspace.dimensions()'''
* ''bool'' '''transient''': Whether the Client is a transient Window to another Window. transientFor
*Returns the dimensions of the workspace in pixels.
* ''KWin::AbstractClient *'' '''transientFor''': The Client to which this Client is a transient if any.
 
* ''bool'' '''modal''': Whether the Client represents a modal window.
 
* ''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.
'''workspace.desktopGridSize[ret: qsize]'''
* ''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.
 
* ''bool'' '''decorationHasAlpha''': Whether the decoration is currently using an alpha channel.
'''workspace.desktopGridSize()'''
* ''bool'' '''providesContextHelp''': Whether the Client provides context help. Mostly needed by decorations to decide whether to show the help button or not.
*Returns the desktop size in grid units. In essence, it returns the order of a rectangular matrix, where each element is a virtual desktop and the rows and columns specify the number of virtual desktops and the way of arrangement.
* ''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'' '''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
'''workspace.activeClient[ret: client]'''
* ''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.
 
* ''QByteArray'' '''desktopFileName''': The desktop file name of the application this AbstractClient belongs to. This is either the base name without full path and without file extension of the desktop file for the window's application (e.g. "org.kde.foo"). The application's desktop file name can also be the full path to the desktop file (e.g. "/opt/kde/share/org.kde.foo.desktop") in case it's not in a standard location.
'''workspace.activeClient()'''
* ''bool'' '''hasApplicationMenu''': Whether an application menu is available for this Client
*Returns the client which currently has focus.
* ''bool'' '''applicationMenuActive''': Whether the application menu for this Client is currently opened
 
* ''bool'' '''unresponsive''': Whether this client is unresponsive. When an application failed to react on a ping request in time, it is considered unresponsive. This usually indicates that the application froze or crashed.
 
* ''QString'' '''colorScheme''': The color scheme set on this client Absolute file path, or name of palette in the user's config directory following KColorSchemes format. An empty string indicates the default palette from kdeglobals is used. this indicates the colour scheme requested, which might differ from the theme applied if the colorScheme cannot be found
'''workspace.clientGroups[ret: Array(clientgroup)]'''
=== Read-write Properties ===
 
 
'''workspace.clientGroups()'''
* ''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.
*Returns an array of all the ClientGroups from the current workspace.
* ''int'' '''desktop''': The desktop this Client is on. If the Client is on all desktops the property has value -1. This is a legacy property, use x11DesktopIds instead
 
* ''bool'' '''onAllDesktops''': Whether the Client is on all desktops. That is desktop is -1.
== Properties ==
* ''QStringList'' '''activities''': The activities this client is on. If it's on all activities the property is empty.
'''workspace.currentDesktop [ret: integer] [GO]'''
* ''bool'' '''skipTaskbar''': Indicates that the window should not be included on a taskbar.
*Returns the current desktop number of the workspace.
* ''bool'' '''skipPager''': Indicates that the window should not be included on a Pager.
 
* ''bool'' '''skipSwitcher''': Whether the Client should be excluded from window switching effects.
 
* ''bool'' '''keepAbove''': Whether the Client is set to be kept above other windows.
= toplevel[floating] =
* ''bool'' '''keepBelow''': Whether the Client is set to be kept below other windows.
== Methods ==
* ''bool'' '''shade''': Whether the Client is shaded.
'''toplevel.x[ret: integer]'''
* ''bool'' '''minimized''': Whether the Client is minimized.
 
* ''bool'' '''demandsAttention''': Whether window state _NET_WM_STATE_DEMANDS_ATTENTION is set. This state indicates that some action in or with the window happened. For example, it may be set by the Window Manager if the window requested activation but the Window Manager refused it, or the application may set it if it finished some work. This state may be set by both the Client and the Window Manager. It should be unset by the Window Manager when it decides the window got the required attention (usually, that it got activated).
'''toplevel.x()'''
* ''QRect'' '''geometry''': The geometry of this Client. Be aware that depending on resize mode the frameGeometryChanged signal might be emitted at each resize step or only at the end of the resize operation. DeprecatedUse frameGeometry
*Returns the x co-ordinate of the toplevel client (or the client).
* ''QRect'' '''frameGeometry''': The geometry of this Client. Be aware that depending on resize mode the frameGeometryChanged signal might be emitted at each resize step or only at the end of the resize operation.
 
* ''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 ===
'''toplevel.y[ret: integer]'''
 
 
* '''fullScreenChanged()'''
'''toplevel.y()'''
* '''skipTaskbarChanged()'''
*Returns the y co-ordinate of the toplevel client (or the client).
* '''skipPagerChanged()'''
 
* '''skipSwitcherChanged()'''
 
* '''iconChanged()'''
'''toplevel.width[ret: integer]'''
* '''activeChanged()'''
 
* '''keepAboveChanged(bool)'''
'''toplevel.width()'''
* '''keepBelowChanged(bool)'''
*Returns the width of the toplevel client (or the client).
* '''demandsAttentionChanged()''': Emitted whenever the demands attention state changes.
 
* '''desktopPresenceChanged(KWin::AbstractClient *, int)'''
 
* '''desktopChanged()'''
'''toplevel.height[ret: integer]'''
* '''activitiesChanged(KWin::AbstractClient *client)'''
 
* '''x11DesktopIdsChanged()'''
'''toplevel.height()'''
* '''shadeChanged()'''
*Returns the height of the toplevel client (or the client).
* '''minimizedChanged()'''
 
* '''clientMinimized(KWin::AbstractClient *client, bool animate)'''
 
* '''clientUnminimized(KWin::AbstractClient *client, bool animate)'''
'''toplevel.size[ret: qsize]'''
* '''paletteChanged(const QPalette &p)'''
 
* '''colorSchemeChanged()'''
'''toplevel.size()'''
* '''captionChanged()'''
*Returns the size of the toplevel client (or the client).
* '''clientMaximizedStateChanged(KWin::AbstractClient *, MaximizeMode)'''
 
* '''clientMaximizedStateChanged(KWin::AbstractClient *c, bool h, bool v)'''
 
* '''transientChanged()'''
'''toplevel.pos[ret: qpoint]'''
* '''modalChanged()'''
 
* '''quickTileModeChanged()'''
'''toplevel.pos()'''
* '''moveResizedChanged()'''
*Returns the position of the toplevel client (or the client).
* '''moveResizeCursorChanged(CursorShape)'''
 
* '''clientStartUserMovedResized(KWin::AbstractClient *)'''
 
* '''clientStepUserMovedResized(KWin::AbstractClient *, const QRect &)'''
'''toplevel.opacity[ret: decimal]'''
* '''clientFinishUserMovedResized(KWin::AbstractClient *)'''
 
* '''closeableChanged(bool)'''
'''toplevel.opacity()'''
* '''minimizeableChanged(bool)'''
*Returns the opacity (or 1 - transperency) of the toplevel client (or the client).
* '''shadeableChanged(bool)'''
 
* '''maximizeableChanged(bool)'''
 
* '''desktopFileNameChanged()'''
'''toplevel.hasAlpha[ret: bool]'''
* '''applicationMenuChanged()'''
 
* '''hasApplicationMenuChanged(bool)'''
'''toplevel.hasAlpha()'''
* '''applicationMenuActiveChanged(bool)'''
*Returns (true) if the client can be made translucent i.e. opacity can be set to values other than 0 or 1, (false) otherwise. NOTE: If compositing is OFF, then clients may still show that translucency is possible, but translucency is not possible without compositing being ON.
* '''unresponsiveChanged(bool)'''
 
* '''geometryChanged()'''
 
* '''keepBelowChanged()'''
'''toplevel.setOpacity'''
=== Functions ===
 
 
'''toplevel.setOpacity(opacity_v {decimal})'''
* '''closeWindow()=0'''
*Sets the opacity of the client to opacity_v or sets transperency to (1 - opacity_v). NOTE: If compositing is OFF, this function has no effect for any values between 0 and 1 (exclusive).
* '''setMaximize(bool vertically, bool horizontally)''': Sets the maximization according to vertically and horizontally.
 
 
'''setOpacity(opacity_v {decimal})'''
*opacity_v {decimal}: The opacity to be set (on a scale of 0-1).
 
 
= client[floating] =
== Events ==
'''client.clientMoved'''
*Emitted whenever the client is moved or it's geometry changed. This includes when a client is resized.
 
 
'''client.minimized'''
*Emitted whenever a client is minimized. Equivalent to workspace.clientMinimized, but for a specific client. Use wherever possible instead of workspace.clientMinimzed to improve performance.
 
 
'''client.maximizeSet'''
*Emitted when the client is maximized in a particular orientation. The orientation i.e. the rectangular direction in which the client was specified to occupy the entire available space is specified by the two parameters horizontally and vertically. If both are true, the client was maximized fully i.e. asked to occupy the entire workspace are available. Equivalent to workspace.clientMaximizeSet, but for a specific client. Use wherever possible instead of workspace.clientMaximizeSet to improve performance.
**'''horizontally {boolean}''': (true) if the client was maximized horizontally, (false) otherwise.
**'''vertically {boolean}''': (true) if the client was maximized vertically, (false) otherwise.
 
 
'''client.activated'''
*Emitted whenever the client is activated (or gets focus). Equivalent to workspace.clientActivated but for a specific client. Use wherever possible instead of workspace.clientActivated to improve performance.
 
 
'''client.unminimized'''
*Emitted whenever the given client is unminimized. Equivalent of workspace.clientUnminimzed but for a specific client. Use wherever possible instead of workspace.clientUnminimized to improve performance.
 
 
'''client.fullScreenSet'''
*Emitted whenever the client's fullscreen mode is toggled. fss_set specifies whether the client was set to or from fullscreen mode.
**'''fss_set {boolean}''': (true) if the client was set to full screen mode, (false) if the client was set from full screen mode.
 
== Methods ==
'''client.caption[ret: string]'''
 
'''client.caption()'''
*Returns the caption of the caption (or the title) of the window.
 
 
'''client.close'''
 
'''client.close()'''
*Closes the given client using killClient.
 
 
'''client.move[variable parameter styles]'''
 
'''client.move(location {qpoint}, emitjs {boolean})'''
 
'''client.move(x {integer}, y {integer}, emitjs {boolean})'''
*Moves the client to the specified location keeping the height and width of the client same.
**'''location {qpoint}''': The (x, y) point to where the top left corner of the client must be moved to keeping the current height and width same.
**'''emitjs {boolean}''': EmitJS value (defaults to true).
**'''x {integer}''': The x co-ordinate value of the point to where the top left corner of the client must be moved to keeping the current height and width same.
**'''y {integer}''': The y co-ordinate value of the point to where the top left corner of the client must be moved to keeping the current height and width same.
 
 
'''client.resize[variable parameter styles]'''
 
'''client.resize(size {qsize}, emitJS {boolean})'''
 
'''client.resize(w {integer}, h {integer}, emitJS {boolean})'''
*Resizes the client to the specified size without changing its position.
**'''size {qsize}''': The size to which the client is to be resized.
**'''emitJS {boolean}''': EmitJS value (defaults to true).
**'''w {integer}''': New width for the client.
**'''h {integer}''': New height for the client.
**'''emitJS {boolean}''': EmitJS value (defaults to true).
 
 
'''client.setGeometry[variable parameter styles]'''
 
'''client.setGeometry(geometry {qrect}, emitJS {boolean})'''
 
'''client.setGeometry(x {integer}, y {integer}, w {integer}, h {integer})'''
*Sets the geometry of the client i.e. sets is size and location according to the provided parameters.
**'''geometry {qrect}''': The new geometry which is to be set for the client.
**'''emitJS {boolean}''': EmitJS value (defaults to true).
**'''x {integer}''': The x co-ordinate of the new geometry.
**'''y {integer}''': The y co-ordinate of the new geometry.
**'''w {integer}''': The width of the new geometry.
**'''h {integer}''': The height of the new geometry.
 
 
'''client.getWindowInfo[ret: windowinfo]'''
 
'''client.getWindowInfo()'''
*Returns a windowinfo object which can be used to get further information about the client. Wherever possible, directly use the client properties than calling for a windowinfo object. NOTE: The windowinfo object is a 'snapshot' object and hence the data provided by it is not modified when the properties of the client are changed.
 
 
'''client.isTransient[ret: boolean]'''
 
'''client.isTransient()'''
*Returns (true) is 'client' is transient, (false) otherwise.
 
 
'''client.isTransientFor[ret: client]'''
 
'''client.isTransientFor()'''
*If the given client is transient, returns it's parent client, otherwise returns an undefined scriptvalue.
 
 
'''client.activate'''
'''client.activate()'''
*Attempt to activate (focus) the client. By attempt, it means that focus stealing prevention still is activated and the rules for activation are in place. Hence, the client actually may nor may not be activated.
 
 
'''client.setCaption'''
 
'''client.setCaption(caption_string {string})'''
*Sets the caption for the specified client to caption_string.
**'''caption_string {string}''': The caption to be set for the specified.
 
 
'''client.unminimize'''
 
'''client.unminimize()'''
*Unminimizes (or restores) the given client.
 
 
'''client.setFullScreen'''
 
'''client.setFullScreen( {fss_set})'''
*Sets the client to or from full screen mode.
**'''{fss_set}''': If (true), then the client is set to full screen or else, it is unset from fullscreen mode. If no parameter is provided, it toggles the full screen state.
 
 
'''client.isShade[ret: boolean]'''
 
'''client.isShade()'''
*Returns (true) of the client is shaded, (false) otherwise.
 
 
'''client.isShadeable[ret: boolean]'''
 
'''client.isShadeable()'''
*Returns (true) of the client is shadeable (can be shaded), (false) otherwise.
 
 
'''client.isMinimized[ret: boolean]'''
 
'''client.isMinimized()'''
*Returns (true) of the client is minimized, (false) otherwise.
 
 
'''client.isMinimizable[ret: boolean]'''
 
'''client.isMinimizable()'''
*Returns (true) of the client can be minimized, (false) otherwise.
 
 
'''client.isMaximizable[ret: boolean]'''
 
'''client.isMaximizable()'''
*Returns (true) of the client can be mazimized, (false) otherwise.
 
 
'''client.isResizable[ret: boolean]'''
 
'''client.isResizable()'''
*Returns (true) of the client can be resized (changable size), (false) otherwise.
 
 
'''client.isMovable[ret: boolean]'''
 
'''client.isMovable()'''
*Returns (true) of the client can be moved (non-fixed location), (false) otherwise.
 
 
'''client.isMovableAcrossScreens[ret: boolean]'''
 
'''client.isMovableAcrossScreens()'''
*Returns (true) of the client can be moved across screens (only valid in a multiple monitor setup), (false) otherwise.
 
 
'''client.isCloseable[ret: boolean]'''
 
'''client.isCloseable()'''
*Returns (true) of the client can be closed by user action (or any other action other than the system or the application itself), (false) otherwise.
 
 
'''client.isFullScreen[ret: boolean]'''
 
'''client.isFullScreen()'''
*Returns (true) of the client is in fullscreen mode, (false) otherwise.
 
 
'''client.isFullScreenable[ret: boolean]'''
 
'''client.isFullScreenable()'''
*Returns (true) of the client can be set to fullscreen mode, (false) otherwise.
 
 
'''client.clientGroup[ret: clientgroup]'''
 
'''client.clientGroup()'''
*Returns the client group the client belongs to. If it belongs to no client, it returns an undefined script value.
 
 
'''client.desktop[ret: integer]'''
 
'''client.desktop()'''
*Returns the desktop number that the client is on. If it is on all desktops, it returns -1.
 
 
= clientgroup[instantiable] =
== Methods ==
 
'''clientgroup.ClientGroup[constructor]'''
 
'''clientgroup.ClientGroup(seed_client {client})'''
*Creates a new clientgroup object. A clientgroup in essence refers to a group of tabbed clients and an object refers to a specific group of such tabbed clients. It returns a clientgroup object which can be then manipulated using the various accessor functions.
**'''seed_client {client}''': The client to be added to the newly formed clientgroup. This is a mandatory argument for the creation of a new clientgroup object.
 
 
'''clientgroup.add'''
 
'''clientgroup.add(new_client {client}, beforeClient {integer}, becomeVisible {boolean})'''
*Adds new_client to the clientgroup at the index specified by beforeClient and if becomeVisible is true, makes it visible.
**'''new_client {client}''': A client object to be added to the clientgroup.
**'''beforeClient {integer}''': An index as to where the client is to be added to the clientgroup. It is an optional argument and if not specified, it will be added at the last position in the clientgroup.
becomeVisible {boolean}: If (true), makes the added client visible.
 
 
'''clientgroup.remove[variable parameter styles]'''
 
'''clientgroup.remove(index {integer}, set_geom {qrect})'''
 
'''clientgroup.remove(rem_client {client}, set_geom {qrect})'''
*Removes the client from the clientgroup and then sets it's geometry according to set_geom. This parameter is optional.
**'''index {integer}''': The client index which is to be removed.
**'''set_geom {qrect}''': The geometry to be set after removeal. This parameter is optional.
**'''rem_client {client}''': The client which is to be removed.
**'''set_geom {qrect}''': The geometry to be set after removal.
 
 
'''clientgroup.clients[ret: Array(client)]'''
 
'''clientgroup.clients()'''
*Returns an array of all the member clients of the clientgroup.
 
 
'''clientgroup.contains[ret: boolean]'''
 
'''clientgroup.contains(needle_client {client})'''
*Returns (true) if needle_client is a member of the clientgroup, (false) otherwise.
**'''needle_client {client}''': The client to be searched for
 
 
'''clientgroup.indexOf[ret: integer]'''
 
'''clientgroup.indexOf(needle_client {client})'''
*Searches for needle_client in the clientgroup and returns the position at which it exists. If needle_client is not found, then it returns -1.
**'''needle_client {client}''': The client whose index is to be found
 
 
'''clientgroup.move[variable parameter styles]'''
 
'''clientgroup.move(index_a {integer}, index_b {integer})'''
 
'''clientgroup.move(move_client {integer}, index {integer})'''
 
'''clientgroup.move(move_client {integer}, before_client {integer})'''
 
'''clientgroup.move(index_a {integer}, before_client {integer})'''
*Move a client within the group. Accepts move(client, client), move(index, index), move(index, client), move(client, index). All calls except move(client, client) are eventually mapped to move(index, index) using indexOf(client)
**'''index_a {integer}''': The index of the client to be moved.
**'''index_b {integer}''': The index of the position to move the client to.
**'''move_client {integer}''': The client to be moved.
**'''index {integer}''': The index of the position to move the client to.
**'''move_client {integer}''': The client to be moved.
**'''before_client {integer}''': The client before which the client is to moved.
**'''index_a {integer}''': The index of the client to be moved.
**'''before_client {integer}''': The client before which the client is to moved.
 
 
'''clientgroup.removeAll'''
 
'''clientgroup.removeAll()'''
*Removes all the clients from the clientgroup i.e. completely disassembles the clientgroup into its proponents.
 
 
'''clientgroup.closeAll'''
 
'''clientgroup.closeAll()'''
*Closes all the clients presents in the clientgroup.
 
 
'''clientgroup.minSize[ret: qsize]'''
 
'''clientgroup.minSize()'''
*Returns the minimum size acceptable for the clientgroup computed from the minimum sizes of all its present members.
 
 
'''clientgroup.maxSize[ret: qsize]'''
 
'''clientgroup.maxSize()'''
*Returns the maximum size acceptable for the clientgroup computed from the minimum sizes of all its present members.
 
= windowinfo[floating] =
== Properties ==
'''windowinfo.isValid [ret: boolean] [GO]'''
*Returns (true) if the client is valid, (false) otherwise.
 
 
'''windowinfo.visibleName [ret: string] [GO]'''
*Returns the visible name of the client.
 
 
'''windowinfo.isMinimized [ret: boolean] [GO]'''
*Returns (true) if client is minimized. Redundant with client.isMinimized. For client, the subclass property is called, not the toplevel one.
 
 
'''windowinfo.state [ret: integer] [GO]'''
*Returns an integeral state for the client. Prefer other methods like isShaded, isFullScreenSet etc. over this.
 
 
'''windowinfo.windowRole [ret: string] [GO]'''
*Returns the window role of the toplevel client.
 
 
'''windowinfo.windowClassClass [ret: string] [GO]'''
*Returns the windowclass class of the client.
 
 
'''windowinfo.windowClassName [ret: string] [GO]'''
*Returns the windowclass name of the client.
 
 
= config[singleton] =
== Methods ==
 
'''config.exists'''
 
'''config.exists(config_key {string})'''
*Searches for config_key in the configuration array and returns (true) if a corresponding value exists, (false) otherwise.
**'''config_key {string}''': The configuration key to be seeked.
 
 
'''config.get[variable parameter styles]'''
 
'''config.get()'''
 
'''config.get(key1, key2 ... keyN {string})'''
 
'''config.get(key {string})'''
 
'''config.get(keyArray {Array(string)}, showNonAssoc {boolean})'''
*If called without parameters, returns an associative array in the format ["key" : "value"] of all available key value pairs. If only a single key is requested for (passing 1 string parameter), then the corresponding value is returned and NOT an array. If multiple keys are provided as multiple arguments, an associative array is returned. If multiple keys (or a single) key is provided as an Array, then an associative array is present (if showNonAssoc is false or it is not specified), otherwise returns an integer indexed array.
**'''key1, key2 ... keyN {string}''': A list of keys to search the values for.
**'''key {string}''': The key to search the value for.
**'''keyArray {Array(string)}''': An array of keys to search the corresponding values for.
**'''showNonAssoc {boolean}''': If (true) causes the function to return an integer-indexed array, otherwise returns an associative array in the form ["key" : "value"]. This parameter is optional, defaults to false
 
== Properties ==
'''config.loaded [ret: boolean] [GO]'''
*Returns (true) if a configuration file was found and loaded, (false) otherwise.

Revision as of 18:06, 10 March 2021

This page describes the KWin Scripting API as of KWin 5.21. It has been generated using https://invent.kde.org/nicolasfella/kwin-scripting-api-generator

Global

Methods and properties added to the global JavaScript object.

Read-only Properties

  • KWin::Options options: Global property to all configuration values of KWin core.
  • KWin::Workspace workspace: Global property to the core wrapper of KWin.
  • object KWin: Provides access to enums defined in KWin::WorkspaceWrapper

Functions

  • print(QVariant ... values): Prints all provided values to kDebug and as a D-Bus signal
  • QVariant readConfig(QString key, QVariant defaultValue = QVariant()): Reads the config value for key in the Script's configuration with the optional default value. If not providing a default value and no value stored in the configuration an undefined value is returned.
  • bool registerScreenEdge(ElectricBorder border, QScriptValue callback): Registers the callback for the screen edge. When the mouse gets pushed against the given edge the callback will be invoked. Scripts can also add "X-KWin-Border-Activate" to their metadata file to have the effect listed in the screen edges KCM. This will write an entry BorderConfig= in the script configuration object with a list of ScreenEdges the user has selected.
  • bool unregisterScreenEdge(ElectricBorder border): Unregisters the callback for the screen edge. This will disconnect all callbacks from this script to that edge.
  • bool registerShortcut(QString title, QString text, QString keySequence, QScriptValue callback): Registers keySequence as a global shortcut. When the shortcut is invoked the callback will be called. Title and text are used to name the shortcut and make it available to the global shortcut configuration module.
  • bool assert(bool value, QString message = QString()): Aborts the execution of the script if value does not evaluate to true. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
  • bool assertTrue(bool value, QString message = QString()): Aborts the execution of the script if value does not evaluate to true. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
  • bool assertFalse(bool value, QString message = QString()): Aborts the execution of the script if value does not evaluate to false. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
  • bool assertEquals(QVariant expected, QVariant actual, QString message = QString()): Aborts the execution of the script if the actual value is not equal to the expected value. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
  • bool assertNull(QVariant value, QString message = QString()): Aborts the execution of the script if value is not null. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
  • bool assertNotNull(QVariant value, QString message = QString()): Aborts the execution of the script if value is null. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.
  • callDBus(QString service, QString path, QString interface, QString method, QVariant arg..., QScriptValue callback = QScriptValue()): Call a D-Bus method at (service, path, interface and method). A variable number of arguments can be added to the method call. The D-Bus call is always performed in an async way invoking the callback provided as the last (optional) argument. The reply values of the D-Bus method call are passed to the callback.
  • registerUserActionsMenu(QScriptValue callback): Registers the passed in callback to be invoked whenever the User actions menu (Alt+F3 or right click on window decoration) is about to be shown. The callback is invoked with a reference to the Client for which the menu is shown. The callback can return either a single menu entry to be added to the menu or an own sub menu with multiple entries. The object for a menu entry should be {title: "My Menu entry", checkable: true, checked: false, triggered: function (action) { // callback with triggered QAction}}, for a menu it should be {title: "My menu", items: [{...}, {...}, ...] /*list with entries as described*/}


KWin::WorkspaceWrapper

Enums

ClientAreaOption

  • PlacementArea: window movement snapping area? ignore struts
  • MovementArea:
  • MaximizeArea:
  • MaximizeFullArea:
  • FullScreenArea:
  • WorkArea:
  • FullArea:
  • ScreenArea:

ElectricBorder

  • ElectricTop:
  • ElectricTopRight:
  • ElectricRight:
  • ElectricBottomRight:
  • ElectricBottom:
  • ElectricBottomLeft:
  • ElectricLeft:
  • ElectricTopLeft:
  • ELECTRIC_COUNT:
  • ElectricNone:

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. Deprecatedsince 5.0 use virtualScreenSize
  • int displayWidth: The width of the display, that is width of all combined screens. Deprecatedsince 5.0 use virtualScreenSize
  • int displayHeight: The height of the display, that is height of all combined screens. Deprecatedsince 5.0 use virtualScreenSize
  • int activeScreen
  • int numScreens
  • QStringList activities
  • QSize virtualScreenSize: The bounding size of all screens combined. Overlapping areas are not counted multiple times. virtualScreenGeometry
  • QRect virtualScreenGeometry: The bounding geometry of all outputs combined. Always starts at (0,0) and has virtualScreenSize as it's size. virtualScreenSize

Read-write Properties

  • int currentDesktop
  • KWin::AbstractClient * activeClient
  • int desktops: The number of desktops currently used. Minimum number of desktops is 1, maximum 20.
  • QString currentActivity

Signals

  • desktopPresenceChanged(KWin::AbstractClient *client, int desktop)
  • currentDesktopChanged(int desktop, KWin::AbstractClient *client)
  • clientAdded(KWin::AbstractClient *client)
  • clientRemoved(KWin::AbstractClient *client)
  • clientManaging(KWin::X11Client *client)
  • clientMinimized(KWin::AbstractClient *client)
  • clientUnminimized(KWin::AbstractClient *client)
  • clientRestored(KWin::X11Client *client)
  • clientMaximizeSet(KWin::AbstractClient *client, bool h, bool v)
  • killWindowCalled(KWin::X11Client *client)
  • clientActivated(KWin::AbstractClient *client)
  • clientFullScreenSet(KWin::X11Client *client, bool fullScreen, bool user)
  • clientSetKeepAbove(KWin::X11Client *client, bool keepAbove)
  • numberDesktopsChanged(uint 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.
  • desktopLayoutChanged(): Signal emitted whenever the layout of virtual desktops changed. That is desktopGrid(Size/Width/Height) will have new values. 4.11
  • clientDemandsAttentionChanged(KWin::AbstractClient *client, bool set): The demands attention state for Client c changed to set. c The Client for which demands attention changed set New value of demands attention
  • numberScreensChanged(int count): Signal emitted when the number of screens changes. count The new number of screens
  • screenResized(int screen): This signal is emitted when the size of screen changes. Don't forget to fetch an updated client area.
  • currentActivityChanged(const QString &id): Signal emitted whenever the current activity changed. id id of the new activity
  • activitiesChanged(const QString &id): Signal emitted whenever the list of activities changed. id id of the new activity
  • activityAdded(const QString &id): This signal is emitted when a new activity is added id id of the new activity
  • activityRemoved(const QString &id): This signal is emitted when the activity is removed id id of the removed activity
  • virtualScreenSizeChanged(): Emitted whenever the virtualScreenSize changes. virtualScreenSize() 5.0
  • virtualScreenGeometryChanged(): Emitted whenever the virtualScreenGeometry changes. virtualScreenGeometry() 5.0

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()
  • slotWindowQuickTileTop()
  • slotWindowQuickTileBottom()
  • 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()
  • sendClientToScreen(KWin::AbstractClient *client, int screen): Sends the AbstractClient to the given screen.
  • showOutline(const QRect &geometry): Shows an outline at the specified geometry. If an outline is already shown the outline is moved to the new position. Use hideOutline to remove the outline again.
  • showOutline(int x, int y, int width, int height): Overloaded method for convenience.
  • hideOutline(): Hides the outline previously shown by showOutline.
  • 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 KWin::AbstractClient *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.
  • createDesktop(int position, const QString &name) const: Create a new virtual desktop at the requested position. position The position of the desktop. It should be in range [0, count]. name The name for the new desktop, if empty the default name will be used.
  • removeDesktop(int position) const: Remove the virtual desktop at the requested position position The position of the desktop to be removed. It should be in range [0, count - 1].
  • QString supportInformation() const: Provides support information about the currently running KWin instance.
  • KWin::X11Client * getClient(qulonglong windowId): Finds the Client with the given windowId. windowId The window Id of the Client The found Client or null


KWin::Options

Enums

FocusPolicy

  • ClickToFocus: Clicking into a window activates it. This is also the default.
  • FocusFollowsMouse: Moving the mouse pointer actively onto a normal window activates it. For convenience, the desktop and windows on the dock are excluded. They require clicking.
  • FocusUnderMouse: The window that happens to be under the mouse pointer becomes active. The invariant is: no window can have focus that is not under the mouse. This also means that Alt-Tab won't work properly and popup dialogs are usually unsable with the keyboard. Note that the desktop and windows on the dock are excluded for convenience. They get focus only when clicking on it.
  • FocusStrictlyUnderMouse: This is even worse than FocusUnderMouse. Only the window under the mouse pointer is active. If the mouse points nowhere, nothing has the focus. If the mouse points onto the desktop, the desktop has focus. The same holds for windows on the dock.

WindowOperation

  • MaximizeOp:
  • RestoreOp:
  • MinimizeOp:
  • MoveOp:
  • UnrestrictedMoveOp:
  • ResizeOp:
  • UnrestrictedResizeOp:
  • CloseOp:
  • OnAllDesktopsOp:
  • ShadeOp:
  • KeepAboveOp:
  • KeepBelowOp:
  • OperationsOp:
  • WindowRulesOp:
  • ToggleStoreSettingsOp:
  • HMaximizeOp:
  • VMaximizeOp:
  • LowerOp:
  • FullScreenOp:
  • NoBorderOp:
  • NoOp:
  • SetupWindowShortcutOp:
  • ApplicationRulesOp:

MouseCommand

  • MouseRaise:
  • MouseLower:
  • MouseOperationsMenu:
  • MouseToggleRaiseAndLower:
  • MouseActivateAndRaise:
  • MouseActivateAndLower:
  • MouseActivate:
  • MouseActivateRaiseAndPassClick:
  • MouseActivateAndPassClick:
  • MouseMove:
  • MouseUnrestrictedMove:
  • MouseActivateRaiseAndMove:
  • MouseActivateRaiseAndUnrestrictedMove:
  • MouseResize:
  • MouseUnrestrictedResize:
  • MouseShade:
  • MouseSetShade:
  • MouseUnsetShade:
  • MouseMaximize:
  • MouseRestore:
  • MouseMinimize:
  • MouseNextDesktop:
  • MousePreviousDesktop:
  • MouseAbove:
  • MouseBelow:
  • MouseOpacityMore:
  • MouseOpacityLess:
  • MouseClose:
  • MouseNothing:

MouseWheelCommand

  • MouseWheelRaiseLower:
  • MouseWheelShadeUnshade:
  • MouseWheelMaximizeRestore:
  • MouseWheelAboveBelow:
  • MouseWheelPreviousNextDesktop:
  • MouseWheelChangeOpacity:
  • MouseWheelNothing:

GlSwapStrategy

  • CopyFrontBuffer:
  • PaintFullScreen:
  • ExtendDamage:
  • AutoSwapStrategy:

Read-only Properties

  • bool focusPolicyIsReasonable

Read-write Properties

  • FocusPolicy focusPolicy
  • XwaylandCrashPolicy xwaylandCrashPolicy
  • int xwaylandMaxCrashCount
  • bool nextFocusPrefersMouse
  • bool clickRaise: Whether clicking on a window raises it in FocusFollowsMouse mode or not.
  • bool autoRaise: Whether autoraise is enabled FocusFollowsMouse mode or not.
  • int autoRaiseInterval: Autoraise interval.
  • int delayFocusInterval: Delayed focus interval.
  • bool shadeHover: Whether shade hover is enabled or not.
  • int shadeHoverInterval: Shade hover interval.
  • bool separateScreenFocus: Whether to see Xinerama screens separately for focus (in Alt+Tab, when activating next client)
  • int placement
  • int borderSnapZone: The size of the zone that triggers snapping on desktop borders.
  • int windowSnapZone: The size of the zone that triggers snapping with other windows.
  • int centerSnapZone: The size of the zone that triggers snapping on the screen center.
  • bool snapOnlyWhenOverlapping: Snap only when windows will overlap.
  • bool rollOverDesktops: Whether or not we roll over to the other edge when switching desktops past the edge.
  • int focusStealingPreventionLevel: 0 - 4 , see Workspace::allowClientActivation()
  • KWin::Options::WindowOperation operationTitlebarDblClick
  • KWin::Options::WindowOperation operationMaxButtonLeftClick
  • KWin::Options::WindowOperation operationMaxButtonMiddleClick
  • KWin::Options::WindowOperation operationMaxButtonRightClick
  • MouseCommand commandActiveTitlebar1
  • MouseCommand commandActiveTitlebar2
  • MouseCommand commandActiveTitlebar3
  • MouseCommand commandInactiveTitlebar1
  • MouseCommand commandInactiveTitlebar2
  • MouseCommand commandInactiveTitlebar3
  • MouseCommand commandWindow1
  • MouseCommand commandWindow2
  • MouseCommand commandWindow3
  • MouseCommand commandWindowWheel
  • MouseCommand commandAll1
  • MouseCommand commandAll2
  • MouseCommand commandAll3
  • uint keyCmdAllModKey
  • bool showGeometryTip: Whether the Geometry Tip should be shown during a window move/resize.
  • bool condensedTitle: Whether the visible name should be condensed.
  • bool electricBorderMaximize: Whether a window gets maximized when it reaches top screen edge while being moved.
  • bool electricBorderTiling: Whether a window is tiled to half screen when reaching left or right screen edge while been moved.
  • float electricBorderCornerRatio: Whether a window is tiled to half screen when reaching left or right screen edge while been moved.
  • bool borderlessMaximizedWindows
  • int killPingTimeout: timeout before non-responding application will be killed after attempt to close.
  • bool hideUtilityWindowsForInactive: Whether to hide utility windows for inactive applications.
  • int compositingMode
  • bool useCompositing
  • int hiddenPreviews
  • int glSmoothScale: 0 = no, 1 = yes when transformed, 2 = try trilinear when transformed; else 1, -1 = auto
  • bool xrenderSmoothScale
  • bool glStrictBinding
  • bool glStrictBindingFollowsDriver: Whether strict binding follows the driver or has been overwritten by a user defined config value. If true glStrictBinding is set by the OpenGL Scene during initialization. If false glStrictBinding is set from a config value and not updated during scene initialization.
  • bool glCoreProfile
  • GlSwapStrategy glPreferBufferSwap
  • KWin::OpenGLPlatformInterface glPlatformInterface
  • bool windowsBlockCompositing
  • LatencyPolicy latencyPolicy
  • RenderTimeEstimator renderTimeEstimator

Signals

  • focusPolicyChanged()
  • focusPolicyIsResonableChanged()
  • xwaylandCrashPolicyChanged()
  • xwaylandMaxCrashCountChanged()
  • nextFocusPrefersMouseChanged()
  • clickRaiseChanged()
  • autoRaiseChanged()
  • autoRaiseIntervalChanged()
  • delayFocusIntervalChanged()
  • shadeHoverChanged()
  • shadeHoverIntervalChanged()
  • separateScreenFocusChanged(bool)
  • placementChanged()
  • borderSnapZoneChanged()
  • windowSnapZoneChanged()
  • centerSnapZoneChanged()
  • snapOnlyWhenOverlappingChanged()
  • rollOverDesktopsChanged(bool enabled)
  • focusStealingPreventionLevelChanged()
  • operationTitlebarDblClickChanged()
  • operationMaxButtonLeftClickChanged()
  • operationMaxButtonRightClickChanged()
  • operationMaxButtonMiddleClickChanged()
  • commandActiveTitlebar1Changed()
  • commandActiveTitlebar2Changed()
  • commandActiveTitlebar3Changed()
  • commandInactiveTitlebar1Changed()
  • commandInactiveTitlebar2Changed()
  • commandInactiveTitlebar3Changed()
  • commandWindow1Changed()
  • commandWindow2Changed()
  • commandWindow3Changed()
  • commandWindowWheelChanged()
  • commandAll1Changed()
  • commandAll2Changed()
  • commandAll3Changed()
  • keyCmdAllModKeyChanged()
  • showGeometryTipChanged()
  • condensedTitleChanged()
  • electricBorderMaximizeChanged()
  • electricBorderTilingChanged()
  • electricBorderCornerRatioChanged()
  • borderlessMaximizedWindowsChanged()
  • killPingTimeoutChanged()
  • hideUtilityWindowsForInactiveChanged()
  • compositingModeChanged()
  • useCompositingChanged()
  • hiddenPreviewsChanged()
  • glSmoothScaleChanged()
  • xrenderSmoothScaleChanged()
  • glStrictBindingChanged()
  • glStrictBindingFollowsDriverChanged()
  • glCoreProfileChanged()
  • glPreferBufferSwapChanged()
  • glPlatformInterfaceChanged()
  • windowsBlockCompositingChanged()
  • animationSpeedChanged()
  • latencyPolicyChanged()
  • configChanged()
  • renderTimeEstimatorChanged()

Functions

KWin::Toplevel

Read-only Properties

  • bool alpha
  • qulonglong frameId
  • QRect geometry: This property holds the geometry of the Toplevel, excluding invisible portions, e.g. client-side and server-side drop-shadows, etc. DeprecatedUse frameGeometry property instead.
  • QRect bufferGeometry: This property holds rectangle that the pixmap or buffer of this Toplevel occupies on the screen. This rectangle includes invisible portions of the client, e.g. client-side drop shadows, etc.
  • QRect frameGeometry: This property holds the geometry of the Toplevel, excluding invisible portions, e.g. server-side and client-side drop-shadows, etc.
  • QPoint pos: This property holds the position of the Toplevel's frame geometry.
  • QSize size: This property holds the size of the Toplevel's frame geometry.
  • int x: This property holds the x position of the Toplevel's frame geometry.
  • int y: This property holds the y position of the Toplevel's frame geometry.
  • int width: This property holds the width of the Toplevel's frame geometry.
  • int height: This property holds the height of the Toplevel's frame geometry.
  • QRect visibleRect
  • int screen
  • qulonglong windowId
  • int desktop
  • bool onAllDesktops: Whether the window is on all desktops. That is desktop is -1.
  • 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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://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 https://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
  • bool criticalNotification: Returns whether the window is a window with a critical notification.
  • bool onScreenDisplay: Returns whether the window is an On Screen Display.
  • bool comboBox: Returns whether the window is a combobox popup. See _NET_WM_WINDOW_TYPE_COMBO at https://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 https://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
  • int windowType: Returns the NETWM window type See https://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
  • quint32 surfaceId: The Id of the Wayland Surface associated with this Toplevel. On X11 only setups the value is 0.
  • KWaylandServer::SurfaceInterface * surface: Interface to the Wayland Surface. Relevant only in Wayland, in X11 it will be nullptr
  • bool popupWindow: Whether the window is a popup.
  • bool outline: Whether this Toplevel represents the outline. It's always false if compositing is turned off.
  • QUuid internalId: This property holds a UUID to uniquely identify this Toplevel.
  • int pid: The pid of the process owning this window. 5.20

Read-write Properties

  • qreal opacity
  • bool skipsCloseAnimation: Whether the window does not want to be animated on window close. There are legit reasons for this like a screenshot application which does not want it's window being captured.

Signals

  • opacityChanged(KWin::Toplevel *toplevel, qreal oldOpacity)
  • damaged(KWin::Toplevel *toplevel, const QRegion &damage)
  • inputTransformationChanged()
  • geometryChanged(): This signal is emitted when the Toplevel's frame geometry changes. Deprecatedsince 5.19, use frameGeometryChanged instead
  • geometryShapeChanged(KWin::Toplevel *toplevel, const QRect &old)
  • paddingChanged(KWin::Toplevel *toplevel, const QRect &old)
  • windowClosed(KWin::Toplevel *toplevel, KWin::Deleted *deleted)
  • windowShown(KWin::Toplevel *toplevel)
  • windowHidden(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.
  • screenChanged(): Emitted whenever the Toplevel's screen changes. This can happen either in consequence to a screen being removed/added or if the Toplevel's geometry changes. 4.11
  • skipCloseAnimationChanged()
  • windowRoleChanged(): Emitted whenever the window role of the window changes. 5.0
  • windowClassChanged(): Emitted whenever the window class name or resource name of the window changes. 5.0
  • surfaceIdChanged(quint32): Emitted when a Wayland Surface gets associated with this Toplevel. 5.3
  • hasAlphaChanged(): 5.4
  • surfaceChanged(): Emitted whenever the Surface for this Toplevel changes.
  • screenScaleChanged()
  • shadowChanged(): Emitted whenever the client's shadow changes. 5.15
  • bufferGeometryChanged(KWin::Toplevel *toplevel, const QRect &oldGeometry): This signal is emitted when the Toplevel's buffer geometry changes.
  • frameGeometryChanged(KWin::Toplevel *toplevel, const QRect &oldGeometry): This signal is emitted when the Toplevel's frame geometry changes.
  • clientGeometryChanged(KWin::Toplevel *toplevel, const QRect &oldGeometry): This signal is emitted when the Toplevel's client geometry has changed.

Functions

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


KWin::AbstractClient

Enums

Position

  • PositionCenter:
  • PositionLeft:
  • PositionRight:
  • PositionTop:
  • PositionBottom:
  • PositionTopLeft:
  • PositionTopRight:
  • PositionBottomLeft:
  • PositionBottomRight:

ForceGeometry_t

  • NormalGeometrySet:
  • ForceGeometrySet:

SizeMode

  • SizeModeAny:
  • SizeModeFixedW:
  • SizeModeFixedH:
  • SizeModeMax:

SameApplicationCheck

  • RelaxedForActive:
  • AllowCrossProcesses:

Read-only Properties

  • 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 active: Whether this Client is active or not. Use Workspace::activateClient() to activate a Client. Workspace::activateClient
  • QVector< uint > x11DesktopIds: The x11 ids for all desktops this client is in. On X11 this list will always have a length of 1
  • 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.
  • QIcon icon
  • 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 minimizable: Whether the Client can be minimized. The property is evaluated each time it is invoked. Because of that there is no notify signal.
  • QRect iconGeometry: The optional geometry representing the minimized Client in e.g a taskbar. See _NET_WM_ICON_GEOMETRY at https://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.
  • 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.
  • QSize minSize: Minimum size as specified in WM_NORMAL_HINTS
  • QSize maxSize: Maximum size as specified in WM_NORMAL_HINTS
  • 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.
  • bool transient: Whether the Client is a transient Window to another Window. transientFor
  • KWin::AbstractClient * transientFor: The Client to which this Client is a transient if any.
  • bool modal: Whether the Client represents a modal window.
  • 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.
  • bool decorationHasAlpha: Whether the decoration is currently using an alpha channel.
  • bool providesContextHelp: Whether the Client provides context help. Mostly needed by decorations to decide whether to show the help button or not.
  • 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 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 resizeable: Whether the Client can be resized. The property is evaluated each time it is invoked. Because of that there is no notify signal.
  • QByteArray desktopFileName: The desktop file name of the application this AbstractClient belongs to. This is either the base name without full path and without file extension of the desktop file for the window's application (e.g. "org.kde.foo"). The application's desktop file name can also be the full path to the desktop file (e.g. "/opt/kde/share/org.kde.foo.desktop") in case it's not in a standard location.
  • bool hasApplicationMenu: Whether an application menu is available for this Client
  • bool applicationMenuActive: Whether the application menu for this Client is currently opened
  • bool unresponsive: Whether this client is unresponsive. When an application failed to react on a ping request in time, it is considered unresponsive. This usually indicates that the application froze or crashed.
  • QString colorScheme: The color scheme set on this client Absolute file path, or name of palette in the user's config directory following KColorSchemes format. An empty string indicates the default palette from kdeglobals is used. this indicates the colour scheme requested, which might differ from the theme applied if the colorScheme cannot be found

Read-write Properties

  • 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.
  • int desktop: The desktop this Client is on. If the Client is on all desktops the property has value -1. This is a legacy property, use x11DesktopIds instead
  • bool onAllDesktops: Whether the Client is on all desktops. That is desktop is -1.
  • QStringList activities: The activities this client is on. If it's on all activities the property is empty.
  • 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 skipSwitcher: Whether the Client should be excluded from window switching effects.
  • 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 shade: Whether the Client is shaded.
  • bool minimized: Whether the Client is minimized.
  • bool demandsAttention: Whether window state _NET_WM_STATE_DEMANDS_ATTENTION is set. This state indicates that some action in or with the window happened. For example, it may be set by the Window Manager if the window requested activation but the Window Manager refused it, or the application may set it if it finished some work. This state may be set by both the Client and the Window Manager. It should be unset by the Window Manager when it decides the window got the required attention (usually, that it got activated).
  • QRect geometry: The geometry of this Client. Be aware that depending on resize mode the frameGeometryChanged signal might be emitted at each resize step or only at the end of the resize operation. DeprecatedUse frameGeometry
  • QRect frameGeometry: The geometry of this Client. Be aware that depending on resize mode the frameGeometryChanged signal might be emitted at each resize step or only at the end of the resize operation.
  • 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

  • fullScreenChanged()
  • skipTaskbarChanged()
  • skipPagerChanged()
  • skipSwitcherChanged()
  • iconChanged()
  • activeChanged()
  • keepAboveChanged(bool)
  • keepBelowChanged(bool)
  • demandsAttentionChanged(): Emitted whenever the demands attention state changes.
  • desktopPresenceChanged(KWin::AbstractClient *, int)
  • desktopChanged()
  • activitiesChanged(KWin::AbstractClient *client)
  • x11DesktopIdsChanged()
  • shadeChanged()
  • minimizedChanged()
  • clientMinimized(KWin::AbstractClient *client, bool animate)
  • clientUnminimized(KWin::AbstractClient *client, bool animate)
  • paletteChanged(const QPalette &p)
  • colorSchemeChanged()
  • captionChanged()
  • clientMaximizedStateChanged(KWin::AbstractClient *, MaximizeMode)
  • clientMaximizedStateChanged(KWin::AbstractClient *c, bool h, bool v)
  • transientChanged()
  • modalChanged()
  • quickTileModeChanged()
  • moveResizedChanged()
  • moveResizeCursorChanged(CursorShape)
  • clientStartUserMovedResized(KWin::AbstractClient *)
  • clientStepUserMovedResized(KWin::AbstractClient *, const QRect &)
  • clientFinishUserMovedResized(KWin::AbstractClient *)
  • closeableChanged(bool)
  • minimizeableChanged(bool)
  • shadeableChanged(bool)
  • maximizeableChanged(bool)
  • desktopFileNameChanged()
  • applicationMenuChanged()
  • hasApplicationMenuChanged(bool)
  • applicationMenuActiveChanged(bool)
  • unresponsiveChanged(bool)
  • geometryChanged()
  • keepBelowChanged()

Functions

  • closeWindow()=0
  • setMaximize(bool vertically, bool horizontally): Sets the maximization according to vertically and horizontally.
Retrieved from "https://techbase.kde.org/index.php?title=Development/Tutorials/KWin/Scripting/API&oldid=106795"