kdecoration.h

Go to the documentation of this file.

/*****************************************************************
This file is part of the KDE project.

Copyright (C) 2003 Lubos Lunak <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
******************************************************************/

#ifndef KDECORATION_H
#define KDECORATION_H

#include <kdecorations_export.h>

#include <QtGui/QColor>
#include <QtGui/QFont>
#include <QObject>
#include <QtGui/QIcon>
#include <netwm_def.h>
#include <QtGui/QMouseEvent>
#include <KPluginFactory>

#define KWIN_DECORATION_API_VERSION 1

#define KWIN_DECORATION( pluginfactoryname, json, classname ) \
    QObject *createDecorationFactory(QWidget *, QObject *, const QList<QVariant> &) { return new classname(); } \
    K_PLUGIN_FACTORY_WITH_JSON(pluginfactoryname, json, registerPlugin<classname>(QString(), &createDecorationFactory);) \
    K_EXPORT_PLUGIN_VERSION(KWIN_DECORATION_API_VERSION)

#define KWIN_DECORATION_BRIDGE_API_VERSION 1
extern "C" {
    int decoration_bridge_version();
}

class KConfig;
class KConfigGroup;

class KDecorationOptionsPrivate;
class KDecorationBridge;
class KDecorationPrivate;
class KDecorationFactory;

class KDECORATIONS_EXPORT KDecorationDefines
{
public:
    enum Position {
        // without prefix, they'd conflict with Qt::TopLeftCorner etc. :(
        PositionCenter         = 0x00,
        PositionLeft           = 0x01,
        PositionRight          = 0x02,
        PositionTop            = 0x04,
        PositionBottom         = 0x08,
        PositionTopLeft        = PositionLeft | PositionTop,
        PositionTopRight       = PositionRight | PositionTop,
        PositionBottomLeft     = PositionLeft | PositionBottom,
        PositionBottomRight    = PositionRight | PositionBottom
    };
    // these values are written to session files, don't change the order
    enum MaximizeMode {
        MaximizeRestore    = 0, 
        MaximizeVertical   = 1, 
        MaximizeHorizontal = 2, 
        MaximizeFull = MaximizeVertical | MaximizeHorizontal
    };

    enum QuickTileFlag {
        QuickTileNone = 0,
        QuickTileLeft = 1,
        QuickTileRight = 1<<1,
        QuickTileTop = 1<<2,
        QuickTileBottom = 1<<3,
        QuickTileHorizontal = QuickTileLeft|QuickTileRight,
        QuickTileVertical = QuickTileTop|QuickTileBottom,
        QuickTileMaximize = QuickTileLeft|QuickTileRight|QuickTileTop|QuickTileBottom
    };

    Q_DECLARE_FLAGS(QuickTileMode, QuickTileFlag)

    enum WindowOperation {
        MaximizeOp = 5000,
        RestoreOp,
        MinimizeOp,
        MoveOp,
        UnrestrictedMoveOp,
        ResizeOp,
        UnrestrictedResizeOp,
        CloseOp,
        OnAllDesktopsOp,
        ShadeOp,
        KeepAboveOp,
        KeepBelowOp,
        OperationsOp,
        WindowRulesOp,
        ToggleStoreSettingsOp = WindowRulesOp, 
        HMaximizeOp,
        VMaximizeOp,
        LowerOp,
        FullScreenOp,
        NoBorderOp,
        NoOp,
        SetupWindowShortcutOp,
        ApplicationRulesOp,
        RemoveTabFromGroupOp, // Remove from group
        CloseTabGroupOp, // Close the group
        ActivateNextTabOp, // Move left in the group
        ActivatePreviousTabOp, // Move right in the group
        TabDragOp,
    };
    enum ColorType {
        ColorTitleBar,   
        ColorTitleBlend, 
        ColorFont,       
        ColorButtonBg,   
        ColorFrame,      
        ColorHandle,     
        NUM_COLORS       
    };

    enum BorderSize {
        BorderTiny,      
        BorderNormal,    
        BorderLarge,     
        BorderVeryLarge, 
        BorderHuge,      
        BorderVeryHuge,  
        BorderOversized, 
        BorderNoSides,   
        BorderNone,      
        BordersCount     
    };

    enum Ability {
        // announce
        AbilityAnnounceButtons = 0, 
        // buttons
        AbilityButtonMenu = 1000,   
        AbilityButtonOnAllDesktops = 1001, 
        AbilityButtonSpacer = 1002, 
        AbilityButtonHelp = 1003,   
        AbilityButtonMinimize = 1004,  
        AbilityButtonMaximize = 1005, 
        AbilityButtonClose = 1006, 
        AbilityButtonAboveOthers = 1007, 
        AbilityButtonBelowOthers = 1008, 
        AbilityButtonShade = 1009, 
        AbilityButtonResize = 1010, 
        AbilityButtonApplicationMenu = 1011,   
        // compositing
        AbilityProvidesShadow = 3000, 
        AbilityUsesAlphaChannel = 3001, 
        AbilityExtendIntoClientArea = 3002, 
        AbilityUsesBlurBehind = 3003, 
        AbilityAnnounceAlphaChannel = 4004, 
        // Tabbing
        AbilityTabbing = 4000, 
        // TODO colors for individual button types
        ABILITY_DUMMY = 10000000,
    };

    enum Requirement { REQUIREMENT_DUMMY = 1000000 };

    enum Region {
        ExtendedBorderRegion
    };

    enum DecorationButton {
        DecorationButtonNone,
        DecorationButtonMenu,
        DecorationButtonApplicationMenu,
        DecorationButtonOnAllDesktops,
        DecorationButtonQuickHelp,
        DecorationButtonMinimize,
        DecorationButtonMaximizeRestore,
        DecorationButtonClose,
        DecorationButtonKeepAbove,
        DecorationButtonKeepBelow,
        DecorationButtonShade,
        DecorationButtonResize,
        DecorationButtonExplicitSpacer
    };

    static QString tabDragMimeType();

};

class KDecorationProvides
    : public KDecorationDefines
{
public:
    virtual ~KDecorationProvides() {}
    virtual bool provides(Requirement req) = 0;
};

class KDECORATIONS_EXPORT KDecorationOptions : public QObject, public KDecorationDefines
{
    Q_OBJECT
public:
    KDecorationOptions(QObject *parent = nullptr);
    virtual ~KDecorationOptions();
    QColor color(ColorType type, bool active = true) const;
    QPalette palette(ColorType type, bool active = true) const;
    QFont font(bool active = true, bool small = false) const;
    bool customButtonPositions() const;
    QList<DecorationButton> titleButtonsLeft() const;
    static QList<DecorationButton> defaultTitleButtonsLeft();
    QList<DecorationButton> titleButtonsRight() const;
    static QList<DecorationButton> defaultTitleButtonsRight();
    bool showTooltips() const;

    BorderSize preferredBorderSize(KDecorationFactory* factory) const;

    WindowOperation operationMaxButtonClick(Qt::MouseButtons button) const;

    static KDecorationOptions *self();

    static QList<DecorationButton> readDecorationButtons(const KConfigGroup &config, const char *key,
                                                         const QList<DecorationButton> &defaultValue);
    static void writeDecorationButtons(KConfigGroup &config, const char *key,
                                       const QList<DecorationButton> &value);

Q_SIGNALS:
    void colorsChanged();
    void activeFontChanged();
    void inactiveFontChanged();
    void smallActiveFontChanged();
    void smallInactiveFontChanged();
    void fontsChanged();
    void leftButtonsChanged();
    void rightButtonsChanged();
    void customButtonPositionsChanged();
    void buttonsChanged();
    void showTooltipsChanged();
    void borderSizeChanged();
    void configChanged();
    void compositingChanged();

protected:
    void setOpMaxButtonLeftClick(WindowOperation op);
    void setOpMaxButtonRightClick(WindowOperation op);
    void setOpMaxButtonMiddleClick(WindowOperation op);
    void setBorderSize(BorderSize bs);
    void setCustomButtonPositions(bool b);
    void setTitleButtonsLeft(const QList<DecorationButton>& b);
    void setTitleButtonsRight(const QList<DecorationButton>& b);
    void updateSettings(KConfig* config);
private:
    KDecorationOptionsPrivate* d;
    static KDecorationOptions *s_self;
};


class KDECORATIONS_EXPORT KDecoration
    : public QObject, public KDecorationDefines
{
    Q_OBJECT
    Q_PROPERTY(bool active READ isActive NOTIFY activeChanged)
    Q_PROPERTY(QString caption READ caption NOTIFY captionChanged)
    Q_PROPERTY(int desktop READ desktop WRITE setDesktop NOTIFY desktopChanged)
    Q_PROPERTY(bool onAllDesktops READ isOnAllDesktops NOTIFY desktopChanged)
    Q_PROPERTY(bool setShade READ isSetShade NOTIFY shadeChanged)
    Q_PROPERTY(QIcon icon READ icon NOTIFY iconChanged)
    Q_PROPERTY(bool maximized READ isMaximized NOTIFY maximizeChanged)
    Q_PROPERTY(bool keepAbove READ keepAbove WRITE setKeepAbove NOTIFY keepAboveChanged)
    Q_PROPERTY(bool keepBelow READ keepBelow WRITE setKeepBelow NOTIFY keepBelowChanged)
    Q_PROPERTY(bool onAllDesktopsAvailable READ isOnAllDesktopsAvailable NOTIFY onAllDesktopsAvailableChanged)
public:
    KDecoration(KDecorationBridge* bridge, KDecorationFactory* factory);
    virtual ~KDecoration();

    // requests from decoration

    static const KDecorationOptions* options();
    bool isActive() const;
    bool isCloseable() const;
    bool isMaximizable() const;
    MaximizeMode maximizeMode() const;
    bool isMaximized() const;
    QuickTileMode quickTileMode() const;

    bool isMinimizable() const;
    bool providesContextHelp() const;
    int desktop() const;
    bool isOnAllDesktops() const; // convenience
    bool isOnAllDesktopsAvailable() const;
    bool isModal() const;
    bool isShadeable() const;
    bool isShade() const;
    bool isSetShade() const;
    bool keepAbove() const;
    bool keepBelow() const;
    bool isMovable() const;
    bool isResizable() const;
    NET::WindowType windowType(unsigned long supported_types) const;
    QIcon icon() const;
    QString caption() const;
    void showWindowMenu(const QRect &pos);

    void showWindowMenu(QPoint pos);
    void showApplicationMenu(const QPoint& p);
    bool menuAvailable() const;
    void performWindowOperation(WindowOperation op);
    void setMask(const QRegion& reg, int mode = 0);
    void clearMask(); // convenience
    bool isPreview() const;
    QRect geometry() const;
    QRect iconGeometry() const;
    QRegion unobscuredRegion(const QRegion& r) const;
    WId windowId() const;
    int width() const; // convenience
    int height() const;  // convenience
    QRect transparentRect() const;
    void processMousePressEvent(QMouseEvent* e);

    bool isAlphaEnabled() const;

    QPalette palette() const;

    // requests to decoration

    virtual void init() = 0; // called once right after created

    virtual Position mousePosition(const QPoint& p) const = 0;

    // mustn't do any repaints, resizes or anything like that
    virtual void borders(int& left, int& right, int& top, int& bottom) const = 0;
    virtual void resize(const QSize& s) = 0;
    virtual QSize minimumSize() const = 0;

    virtual void render(QPaintDevice *device, const QRegion &sourceRegion);

Q_SIGNALS:
    void activeChanged();
    void captionChanged();
    void desktopChanged();
    void shadeChanged();
    void iconChanged();
    void maximizeChanged();
    void keepAboveChanged();
    void keepBelowChanged();
    void keepAboveChanged(bool);
    void keepBelowChanged(bool);
    void decorationButtonsChanged();

    void menuHidden();
    void showRequest();
    void appMenuAvailable();
    void appMenuUnavailable();

    void alphaEnabledChanged(bool enabled);
    void onAllDesktopsAvailableChanged();

public:
    // TODO position will need also values for top+left+bottom etc. docking ?
    virtual bool windowDocked(Position side);
    virtual void padding(int &left, int &right, int &top, int &bottom) const;

    // special

    void setMainWidget(QWidget*);
    void createMainWidget(Qt::WindowFlags flags = 0);
    void setMainWindow(QWindow *window);
    Qt::WindowFlags initialWFlags() const;
    QWidget* widget();
    const QWidget* widget() const;
    QWindow* window();
    KDecorationFactory* factory() const;
    void grabXServer();
    void ungrabXServer();
    bool compositingActive() const;
    WindowOperation buttonToWindowOperation(Qt::MouseButtons button);
    void show();
    void hide();
    QRect rect() const;


    // Window tabbing

    bool isInActiveTabGroup();
    int tabCount() const;

    QIcon icon(int idx) const;

    QString caption(int idx) const;

    long tabId(int idx) const;
    long currentTabId() const;
    void setCurrentTab(long id);

    virtual void tab_A_before_B(long A, long B);
    virtual void tab_A_behind_B(long A, long B);
    virtual void untab(long id, const QRect& newGeom);

    void closeTab(long id);
    void closeTabGroup();
    void showWindowMenu(const QPoint& pos, long id);

public: // invokables; runtime resolution
    Q_INVOKABLE KDecorationDefines::Position titlebarPosition();

public Q_SLOTS:
    // requests from decoration

    void closeWindow();
    void maximize(Qt::MouseButtons button);
    void maximize(MaximizeMode mode);
    void minimize();
    void showContextHelp();
    void setDesktop(int desktop);
    void toggleOnAllDesktops(); // convenience
    void titlebarDblClickOperation();
    void titlebarMouseWheelOperation(int delta);
    void setShade(bool set);
    void setKeepAbove(bool set);
    void setKeepBelow(bool set);

    void update();
    void update(const QRect &rect);
    void update(const QRegion &region);

protected Q_SLOTS:
    void setAlphaEnabled(bool enabled);
    QRegion region(KDecorationDefines::Region r);

private:
    KDecorationPrivate* d;

};

inline
KDecorationDefines::MaximizeMode operator^(KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2)
{
    return KDecorationDefines::MaximizeMode(int(m1) ^ int(m2));
}

inline
KDecorationDefines::MaximizeMode operator&(KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2)
{
    return KDecorationDefines::MaximizeMode(int(m1) & int(m2));
}

inline
KDecorationDefines::MaximizeMode operator|(KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2)
{
    return KDecorationDefines::MaximizeMode(int(m1) | int(m2));
}

Q_DECLARE_OPERATORS_FOR_FLAGS(KDecoration::QuickTileMode)
Q_DECLARE_METATYPE(KDecorationDefines::WindowOperation)

#endif