Development/Tutorials/KWin/Effects/JS API

Global

Methods and properties added to the global JavaScript object.

Read-only Properties

• KWin::ScriptedEffect effect: Global property to the actual Effect.
• KWin::EffectsHandler effects: Global property to the core wrapper of KWin Effects.

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(int 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 The damaged rect 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
• showOutline(const QRect &outline): Requests to show an outline. An effect providing to show an outline should connect to the signal and render an outline. The outline should be shown till the signal is emitted again with a new geometry or the signal is emitted. outline The geometry of the outline to render. hideOutline 4.7
• hideOutline(): Signal emitted when the outline should no longer be shown. showOutline 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

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::ScriptedEffect

Inherits: KWin::AnimationEffect

Signals

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

Functions

• animate(KWin::EffectWindow *w, Attribute a, int ms, KWin::FPx2 to, KWin::FPx2 from=KWin::FPx2(), KWin::AnimationData *data=NULL, QEasingCurve curve=QEasingCurve(), int delay=0)
• 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