Difference between revisions of "Development/Tutorials/KWin/Effects/JS API"

Revision as of 19:10, 27 October 2012

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

Read-write Properties

Signals

Functions

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

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
• EffectWindowList 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:
• Position:
• Size:
• Translation:
• Clip:
• Generic:
• NonFloatBase:

MetaType

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

Functions

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

Functions

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

• 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