Development/Tutorials/KWin/Effects/JS API

Global

Methods and properties added to the global JavaScript object.

Read-only Properties

• KWin::EffectsHandler effects: Global property to the core wrapper of KWin Effects
• KWin::ScriptedEffect effect: Global property to the actual Effect
• object Effect: Provides access to enums defined in KWin::AnimationEffect and KWin::ScriptedEffect
• object KWin: Provides access to enums defined in KWin::WorkspaceWrapper
• object QEasingCurve: Provides access to enums defined in QEasingCurve

Functions

• QList<quint64> animate(settings): Schedules one or many animations for one window. The animations are defined through the settings object providing

a more declarative way to specify the animations than the animate call on the effect object. The settings object supports the following attributes:

{
    window: EffectWindow, /* the window to animate, required */
    duration: int, /* duration in msec, required */
    curve: QEasingCurve.Type, /* global easing curve, optional */
    type: Effect.Attribute, /* for first animation, optional */
    from: FPx2, /* for first animation, optional */
    to: FPx2, /* for first animation, optional */
    delay: int, /* for first animation, optional */
    animations: [ /* additional animations, optional */
        {
        curve: QEasingCurve.Type, /* overrides global */
        type: Effect.Attribute,
        from: FPx2,
        to: FPx2,
        delay: int
        }
    ]
}

At least one animation or attribute setter (see below) needs to be specified either with the top-level properties or in the animations list.

• QList<quint64> set(settings): Like animate, just that the manipulation does not implicitly end with the animation. You have to explicitly cancel it.

Until then, the manipulated attribute will remain at animation target value.

• bool cancel(QList<quint64>): Cancel one or more present animations caused and returned by KWin::ScriptedEffect::animate or KWin::ScriptedEffect::set.

For convenience you can pass a single quint64 as well.

• print(QVariant ... values): Prints all provided values to kDebug and as a D-Bus signal
• int animationTime(int duration): Adjusts the passed in duration to the global animation time facator.
• int displayWidth(): Width of the complete display (all screens).
• int displayHeight(): Height of the complete display (all screens).
• 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.
• 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.

KWin::FPx2

This class is used to describe the animation end points, that is from which FPx2 values to which FPx2 values an animation goes. This class contains two properties to describe two animation components individually (e.g. width and height). But it's also possible to just have one value (e.g. opacity). In this case the definition of an FPx2 can be replaced by a single value.

Read-write Properties

• qreal value1
• qreal value2

KWin::EffectsHandler

Manager class that handles all the effects.

Read-only Properties

• QString currentActivity
• QSize desktopGridSize
• int desktopGridWidth
• int desktopGridHeight
• int workspaceWidth
• int workspaceHeight
• bool optionRollOverDesktops
• int activeScreen
• int numScreens
• qreal animationTimeFactor: Factor by which animation speed in the effect should be modified (multiplied). If configurable in the effect itself, the option should have also 'default' animation speed. The actual value should be determined using animationTime(). Note: The factor can be also 0, so make sure your code can cope with 0ms time if used manually.
• QList< KWin::EffectWindow * > stackingOrder
• bool decorationsHaveAlpha: Whether window decorations use the alpha channel.
• bool decorationSupportsBlurBehind: Whether the window decorations support blurring behind the decoration.
• CompositingType compositingType
• QPoint cursorPos

Read-write Properties

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

Signals

• desktopChanged(int oldDesktop, int newDesktop, KWin::EffectWindow *with): Signal emitted when the current desktop changed.

oldDesktop

The previously current desktop

newDesktop

The new current desktop

with

The window which is taken over to the new desktop, can be NULL

4.9

• desktopChanged(int oldDesktop, int newDesktop): 4.7

Deprecated

• numberDesktopsChanged(uint old): Signal emitted when the number of currently existing desktops is changed.

old

The previous number of desktops in used.

EffectsHandler::numberOfDesktops. 4.7

• windowAdded(KWin::EffectWindow *w): Signal emitted when a new window has been added to the Workspace.

w

The added window

4.7

• windowClosed(KWin::EffectWindow *w): Signal emitted when a window is being removed from the Workspace. An effect which wants to animate the window closing should connect to this signal and reference the window by using w The window which is being closed 4.7
• windowActivated(KWin::EffectWindow *w): Signal emitted when a window get's activated.

w

The new active window, or NULL if there is no active window.

4.7

• windowDeleted(KWin::EffectWindow *w): Signal emitted when a window is deleted. This means that a closed window is not referenced any more. An effect bookkeeping the closed windows should connect to this signal to clean up the internal references.

w

The window which is going to be deleted.

EffectWindow::refWindow EffectWindow::unrefWindow windowClosed 4.7

• windowStartUserMovedResized(KWin::EffectWindow *w): Signal emitted when a user begins a window move or resize operation. To figure out whether the user resizes or moves the window use or EffectWindow::isUserResize. Whenever the geometry is updated the signal windowStepUserMovedResized is emitted with the current geometry. The move/resize operation ends with the signal windowFinishUserMovedResized. Only one window can be moved/resized by the user at the same time! w The window which is being moved/resized windowStepUserMovedResized windowFinishUserMovedResized EffectWindow::isUserMove EffectWindow::isUserResize 4.7
• windowStepUserMovedResized(KWin::EffectWindow *w, const QRect &geometry): Signal emitted during a move/resize operation when the user changed the geometry. Please note: KWin supports two operation modes. In one mode all changes are applied instantly. This means the window's geometry matches the passed in geometry. In the other mode the geometry is changed after the user ended the move/resize mode. The geometry differs from the window's geometry. Also the window's pixmap still has the same size as before. Depending what the effect wants to do it would be recommended to scale/translate the window.

w

The window which is being moved/resized

geometry

The geometry of the window in the current move/resize step.

windowStartUserMovedResized windowFinishUserMovedResized EffectWindow::isUserMove EffectWindow::isUserResize 4.7

• windowFinishUserMovedResized(KWin::EffectWindow *w): Signal emitted when the user finishes move/resize of window w.

w

The window which has been moved/resized

windowStartUserMovedResized windowFinishUserMovedResized 4.7

• windowMaximizedStateChanged(KWin::EffectWindow *w, bool horizontal, bool vertical): Signal emitted when the maximized state of the window w changed. A window can be in one of four states:

restored: both horizontal and vertical are false horizontally maximized: horizontal is true and vertical is false vertically maximized: horizontal is false and vertical is true completely maximized: both horizontal and vertical are true

w

The window whose maximized state changed

horizontal

If true maximized horizontally

vertical

If true maximized vertically

4.7

• windowGeometryShapeChanged(KWin::EffectWindow *w, const QRect &old): Signal emitted when the geometry or shape of a window changed. This is caused if the window changes geometry without user interaction. E.g. the decoration is changed. This is in opposite to windowUserMovedResized which is caused by direct user interaction.

w

The window whose geometry changed

old

The previous geometry

windowUserMovedResized 4.7

• windowPaddingChanged(KWin::EffectWindow *w, const QRect &old): Signal emitted when the padding of a window changed. (eg. shadow size)

w

The window whose geometry changed

old

The previous expandedGeometry()

4.9

• windowOpacityChanged(KWin::EffectWindow *w, qreal oldOpacity, qreal newOpacity): Signal emitted when the windows opacity is changed.

w

The window whose opacity level is changed.

oldOpacity

The previous opacity level

newOpacity

The new opacity level

4.7

• windowMinimized(KWin::EffectWindow *w): Signal emitted when a window got minimized.

w

The window which was minimized

4.7

• windowUnminimized(KWin::EffectWindow *w): Signal emitted when a window got unminimized.

w

The window which was unminimized

4.7

• windowDamaged(KWin::EffectWindow *w, const QRect &r): Signal emitted when an area of a window is scheduled for repainting. Use this signal in an effect if another area needs to be synced as well.

w

The window which is scheduled for repainting

r

Always empty.

4.7

• tabBoxAdded(int mode): Signal emitted when a tabbox is added. An effect who wants to replace the tabbox with itself should use mode The TabBoxMode. refTabBox tabBoxClosed tabBoxUpdated tabBoxKeyEvent 4.7
• tabBoxClosed(): Signal emitted when the TabBox was closed by KWin core. An effect which referenced the TabBox should use to unref again. unrefTabBox tabBoxAdded 4.7
• tabBoxUpdated(): Signal emitted when the selected TabBox window changed or the TabBox List changed. An effect should only response to this signal if it referenced the TabBox with refTabBox currentTabBoxWindowList currentTabBoxDesktopList currentTabBoxWindow currentTabBoxDesktop 4.7
• tabBoxKeyEvent(QKeyEvent *event): Signal emitted when a key event, which is not handled by TabBox directly is, happens while TabBox is active. An effect might use the key event to e.g. change the selected window. An effect should only response to this signal if it referenced the TabBox with event The key event not handled by TabBox directly refTabBox 4.7
• currentTabAboutToChange(KWin::EffectWindow *from, KWin::EffectWindow *to)
• tabAdded(KWin::EffectWindow *from, KWin::EffectWindow *to)
• tabRemoved(KWin::EffectWindow *c, KWin::EffectWindow *group)
• mouseChanged(const QPoint &pos, const QPoint &oldpos, Qt::MouseButtons buttons, Qt::MouseButtons oldbuttons, Qt::KeyboardModifiers modifiers, Qt::KeyboardModifiers oldmodifiers): Signal emitted when mouse changed. If an effect needs to get updated mouse positions, it needs to first call For a fullscreen effect it is better to use an input window and react on windowInputMouseEvent. pos The new mouse position oldpos The previously mouse position buttons The pressed mouse buttons oldbuttons The previously pressed mouse buttons modifiers Pressed keyboard modifiers oldmodifiers Previously pressed keyboard modifiers. startMousePolling 4.7
• propertyNotify(KWin::EffectWindow *w, long atom): Receives events registered for using Use readProperty() to get the property data. Note that the property may be already set on the window, so doing the same processing from windowAdded() (e.g. simply calling propertyNotify() from it) is usually needed. w The window whose property changed, is null if it is a root window property atom The property 4.7
• screenGeometryChanged(const QSize &size): Signal emitted after the screen geometry changed (e.g. add of a monitor). Effects using displayWidth()/displayHeight() to cache information should react on this signal and update the caches.

size

The new screen size

4.8

• currentActivityChanged(const QString &id): This signal is emitted when the global activity is changed

id

id of the new current activity

4.9

• activityAdded(const QString &id): This signal is emitted when a new activity is added

id

id of the new activity

4.9

• activityRemoved(const QString &id): This signal is emitted when the activity is removed

id

id of the removed activity

4.9

• screenLockingChanged(bool locked): This signal is emitted when the screen got locked or unlocked.

locked

true if the screen is now locked, false if it is now unlocked

4.11

• stackingOrderChanged(): This signels is emitted when ever the stacking order is change, ie. a window is risen or lowered 4.10
• screenEdgeApproaching(ElectricBorder border, qreal factor, const QRect &geometry): This signal is emitted when the user starts to approach the border with the mouse. The factor describes how far away the mouse is in a relative mean. The values are in [0.0, 1.0] with 0.0 being emitted when first entered and on leaving. The value 1.0 means that the border is reached with the mouse. So the values are well suited for animations. The signal is always emitted when the mouse cursor position changes.

border

The screen edge which is being approached

factor

Value in range [0.0,1.0] to describe how close the mouse is to the border

geometry

The geometry of the edge which is being approached

4.11

Functions

• moveWindow(KWin::EffectWindow *w, const QPoint &pos, bool snap=false, double snapAdjust=1.0)=0
• windowToDesktop(KWin::EffectWindow *w, int desktop)=0
• windowToScreen(KWin::EffectWindow *w, int screen)=0
• int desktopAbove(int desktop=0, bool wrap=true) const =0: The ID of the desktop above desktop id. Wraps around to the bottom of the layout if wrap is set. If id is not set use the current one.
• int desktopToRight(int desktop=0, bool wrap=true) const =0: The ID of the desktop to the right of desktop id. Wraps around to the left of the layout if wrap is set. If id is not set use the current one.
• int desktopBelow(int desktop=0, bool wrap=true) const =0: The ID of the desktop below desktop id. Wraps around to the top of the layout if wrap is set. If id is not set use the current one.
• int desktopToLeft(int desktop=0, bool wrap=true) const =0: The ID of the desktop to the left of desktop id. Wraps around to the right of the layout if wrap is set. If id is not set use the current one.
• QString desktopName(int desktop) const =0
• int screenNumber(const QPoint &pos) const =0
• KWin::EffectWindow * findWindow(WId id) const =0
• addRepaintFull()=0: Schedules the entire workspace to be repainted next time. If you call it during painting (including prepaint) then it does not affect the current painting.
• addRepaint(const QRect &r)=0
• addRepaint(const QRegion &r)=0
• addRepaint(int x, int y, int w, int h)=0

KWin::EffectWindow

Representation of a window used by/for Effect classes.

Enums

@15

• PAINT_DISABLED: Window will not be painted
• PAINT_DISABLED_BY_DELETE: Window will not be painted because it is deleted
• PAINT_DISABLED_BY_DESKTOP: Window will not be painted because of which desktop it's on
• PAINT_DISABLED_BY_MINIMIZE: Window will not be painted because it is minimized
• PAINT_DISABLED_BY_TAB_GROUP: Window will not be painted because it is not the active window in a client group
• PAINT_DISABLED_BY_ACTIVITY: Window will not be painted because it's not on the current activity

Read-only Properties

• bool alpha
• QRect geometry
• QRect expandedGeometry
• int height
• qreal opacity
• QPoint pos
• int screen
• QSize size
• int width
• int x
• int y
• int desktop
• bool onAllDesktops
• bool onCurrentDesktop
• QRect rect
• QString windowClass
• QString windowRole
• bool desktopWindow: Returns whether the window is a desktop background window (the one with wallpaper). See _NET_WM_WINDOW_TYPE_DESKTOP at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dock: Returns whether the window is a dock (i.e. a panel). See _NET_WM_WINDOW_TYPE_DOCK at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool toolbar: Returns whether the window is a standalone (detached) toolbar window. See _NET_WM_WINDOW_TYPE_TOOLBAR at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool menu: Returns whether the window is a torn-off menu. See _NET_WM_WINDOW_TYPE_MENU at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool normalWindow: Returns whether the window is a "normal" window, i.e. an application or any other window for which none of the specialized window types fit. See _NET_WM_WINDOW_TYPE_NORMAL at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dialog: Returns whether the window is a dialog window. See _NET_WM_WINDOW_TYPE_DIALOG at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool splash: Returns whether the window is a splashscreen. Note that many (especially older) applications do not support marking their splash windows with this type. See _NET_WM_WINDOW_TYPE_SPLASH at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool utility: Returns whether the window is a utility window, such as a tool window. See _NET_WM_WINDOW_TYPE_UTILITY at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dropdownMenu: Returns whether the window is a dropdown menu (i.e. a popup directly or indirectly open from the applications menubar). See _NET_WM_WINDOW_TYPE_DROPDOWN_MENU at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool popupMenu: Returns whether the window is a popup menu (that is not a torn-off or dropdown menu). See _NET_WM_WINDOW_TYPE_POPUP_MENU at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool tooltip: Returns whether the window is a tooltip. See _NET_WM_WINDOW_TYPE_TOOLTIP at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool notification: Returns whether the window is a window with a notification. See _NET_WM_WINDOW_TYPE_NOTIFICATION at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool comboBox: Returns whether the window is a combobox popup. See _NET_WM_WINDOW_TYPE_COMBO at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool dndIcon: Returns whether the window is a Drag&Drop icon. See _NET_WM_WINDOW_TYPE_DND at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• int windowType: Returns the NETWM window type See http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• bool managed: Whether this EffectWindow 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 EffectWindow represents an already deleted window and only kept for the compositor for animations.
• bool shaped: Whether the window has an own shape
• QRegion shape: The Window's shape
• QString caption: The Caption of the window. Read from WM_NAME property together with a suffix for hostname and shortcut.
• bool keepAbove: Whether the window is set to be kept above other windows.
• bool modal: Whether the window represents a modal window.
• bool moveable: Whether the window is moveable. Even if it is not moveable, it might be possible to move it to another screen. moveableAcrossScreens
• bool moveableAcrossScreens: Whether the window can be moved to another screen. moveable
• QSize basicUnit: By how much the window wishes to grow/shrink at least. Usually QSize(1,1). MAY BE DISOBEYED BY THE WM! It's only for information, do NOT rely on it at all.
• bool move: Whether the window is currently being moved by the user.
• bool resize: Whether the window is currently being resized by the user.
• QRect iconGeometry: The optional geometry representing the minimized Client in e.g a taskbar. See _NET_WM_ICON_GEOMETRY at http://standards.freedesktop.org/wm-spec/wm-spec-latest.html .
• 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.
• QPixmap icon
• bool skipSwitcher: Whether the window should be excluded from window switching effects.
• QRect contentsRect: Geometry of the actual window contents inside the whole (including decorations) window.
• QRect decorationInnerRect: Geometry of the transparent rect in the decoration. May be different from contentsRect if the decoration is extended into the client area.
• bool hasDecoration
• QStringList activities
• bool onCurrentActivity
• bool onAllActivities
• bool decorationHasAlpha: Whether the decoration currently uses an alpha channel. 4.10
• bool visible: Whether the window is currently visible to the user, that is:

Not minimized

On current desktop

On current activity

4.11

Read-write Properties

• bool minimized: Whether the window is minimized.

Functions

• addRepaint(const QRect &r)
• addRepaint(int x, int y, int w, int h)
• addRepaintFull()
• addLayerRepaint(const QRect &r)
• addLayerRepaint(int x, int y, int w, int h)
• bool isOnActivity(QString id) const
• KWin::EffectWindow * findModal()=0
• QList< KWin::EffectWindow * > mainWindows() const =0
• closeWindow() const
• setData(int role, const QVariant &data)=0: Can be used to by effects to store arbitrary data in the EffectWindow.
• QVariant data(int role) const =0

KWin::AnimationEffect

Inherits: KWin::Effect

Enums

Anchor

• Left:
• Top:
• Right:
• Bottom:
• Horizontal:
• Vertical:
• Mouse:

Attribute

• Opacity:
• Brightness:
• Saturation:
• Scale:
• Rotation:
• DecorationOpacity:
• Position:
• Size:
• Translation:
• Clip:
• Generic:
• CrossFadePrevious:
• NonFloatBase:

MetaType

• SourceAnchor:
• TargetAnchor:
• RelativeSourceX:
• RelativeSourceY:
• RelativeTargetX:
• RelativeTargetY:
• Axis:

KWin::AnimationData

Enums

Axis

• XAxis:
• YAxis:
• ZAxis:

Read-write Properties

• KWin::AnimationEffect::Anchor sourceAnchor
• KWin::AnimationEffect::Anchor targetAnchor
• int relativeSourceX
• int relativeSourceY
• int relativeTargetX
• int relativeTargetY
• Axis axis

KWin::ScriptedEffect

Inherits: KWin::AnimationEffect

Enums

DataRole

• WindowAddedGrabRole:
• WindowClosedGrabRole:
• WindowMinimizedGrabRole:
• WindowUnminimizedGrabRole:
• WindowForceBlurRole:
• WindowBlurBehindRole:
• LanczosCacheRole:

Signals

• configChanged(): Signal emitted whenever the effect's config changed.

Functions

• quint64 animate(KWin::EffectWindow *w, Attribute a, int ms, KWin::FPx2 to, KWin::FPx2 from=KWin::FPx2(), KWin::AnimationData *data=NULL, QEasingCurve::Type curve=QEasingCurve::Linear, int delay=0)
• quint64 set(KWin::EffectWindow *w, Attribute a, int ms, KWin::FPx2 to, KWin::FPx2 from=KWin::FPx2(), KWin::AnimationData *data=NULL, QEasingCurve::Type curve=QEasingCurve::Linear, int delay=0)
• bool cancel(quint64 animationId)
• bool borderActivated(ElectricBorder border)
• bool isGrabbed(KWin::EffectWindow *w, DataRole grabRole): Whether another effect has grabbed the w with the given grabRole.

w

The window to check

grabRole

The grab role to check

true if another window has grabbed the effect, false otherwise

• QVariant readConfig(const QString &key, const QVariant defaultValue=QVariant()): Reads the value from the configuration data for the given key.

key

The key to search for

defaultValue

The value to return if the key is not found

The config value if present