Development/Tutorials/KWin/WindowSwitcher

    From KDE TechBase
    Revision as of 19:32, 25 December 2011 by Mgraesslin (talk | contribs) (Initial import of KWin Window Switcher API documentation)
    (diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
    The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

    Introduction

    The Window Switcher (Alt+Tab) can be custom styled using layouts written in QML since KDE Plasma Workspaces in version 4.8. The window manager supports multiple Window Switcher and exchanges the loaded layout at runtime. Additionally the underlying Model is recreated each time the switcher is invoked and some properties might change due to screen changes and different settings for the multiple switchers. To support this the QML loader can set properties in the custom QML Component if available.

    Global Properties

    • int screenWidth: the width of the primary screen. This property can be used to restrain the width of the switcher to the current screen.
    • int screenHeight: the height of the primary screen. This property can be used to restrain the height of the switcher to the current screen.
    • string longestCaption: the window title with most characters at the moment of Model creation. This property can be used to dynamically calculate the width of a list view based on the longest window title.
    • bool allDesktops: whether the Model includes windows from all desktops or only the current desktop. This property can be used to e.g. hide the desktop a window is on when the switcher only shows windows of the current desktop. Do not use this property to filter the list. This is done by the Model.

    If the custom QML layout supports the same properties on the root item, they will be set whenever the layout is loaded and whenever the value changes.

    Model

    The Model is available as a context property clientModel. Additionally the custom component can define a function called setModel(model) which is invoked whenever the Model is set. By that the QML layout can react on the expected Model changes. The component can also define a function called modelChanged() which gets invoked whenever the Model is reset. This happens for example when a window closes while the window switcher is active.

    The Model provides the following roles:

    • string caption: the window title
    • bool minimized: whether the window is minimized
    • string desktopName: the name of the desktop the window is on
    • ulonglong windowId: the window Id (XId) of the window

    Icon

    The window switcher includes an Image Provider to return the window's icon. An image url looks like the following:

    image://client/<index>/<invokation-uid>

    The URL supports an additional suffix /selected to request a highlighted item or /disabled to request an icon in disabled look. E.g.

    image://client/1/1223-324/disabled

    It is important to remember that QML caches the icons. As the URL is based on the Model index which changes from each invocation of the window switcher a unique Id has to be added to disable the cache. This unique Id should be changed whenever the modelChanged() function described above is invoked.

    Model based View

    The window switcher has to set the index in the list view to select the proper item when the switcher is invoked. Because of that the ListView implementation has to follow this contract:

    • Property objectName must have value listView
    • a signal currentIndexChanged(int index) must be defined and invoked whenever the ListView changes the index (e.g. due to mouse click).

    Thumbnails

    The window manager provides a QML component to render a live thumbnail of the window. It is important to know that this thumbnail is not rendered in QML's scene graph, but by the compositor after the window has been rendered. Because of that it is not possible to put other visual components on top of the thumbnail. If compositing is not available an icon will be rendered instead of the thumbnail.

    To use the Thumbnail component import org.kde.kwin in version 0.1. The component is called ThumbnailItem and has one required property wId. Example

    import QtQuick 1.0
    import org.kde.kwin 0.1 as KWin
    ListView {
        objectName: "listView"
        model: clientModel
        delegate: KWin.ThumbnailItem {
            wId: windowId
            width: 200
            height: 200
        }
    }