workspace/kwin/lib/kcommondecoration.h

   1 /*
   2   This file is part of the KDE project.
   3
   4   Copyright (C) 2005 Sandro Giessl <sandro@giessl.com>
   5
   6   Permission is hereby granted, free of charge, to any person obtaining a
   7   copy of this software and associated documentation files (the "Software"),
   8   to deal in the Software without restriction, including without limitation
   9   the rights to use, copy, modify, merge, publish, distribute, sublicense,
  10   and/or sell copies of the Software, and to permit persons to whom the
  11   Software is furnished to do so, subject to the following conditions:
  12
  13   The above copyright notice and this permission notice shall be included in
  14   all copies or substantial portions of the Software.
  15
  16   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  19   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  22   DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 #ifndef KCOMMONDECORATION_H
  26 #define KCOMMONDECORATION_H
  27
  28 #include <QtGui/QAbstractButton>
  29 #include "kdecoration.h"
  30
  31 /** @addtogroup kdecoration */
  32 /** @{ */
  33
  34 class KDecorationBridge;
  35 class KDecorationFactory;
  36
  37 enum ButtonType {
  38     HelpButton=0,
  39     MaxButton,
  40     MinButton,
  41     CloseButton,
  42     MenuButton,
  43     OnAllDesktopsButton,
  44     AboveButton,
  45     BelowButton,
  46     ShadeButton,
  47     NumButtons
  48 };
  49
  50 class KCommonDecorationButton;
  51
  52 class KCommonDecorationButtonPrivate;
  53 class KCommonDecorationPrivate;
  54 class KCommonDecorationWrapper;
  55
  56 /**
  57  * This class eases development of decorations by implementing parts of KDecoration
  58  * which are error prone and common for most decorations.
  59  * It takes care of the window layout, button/action handling, and window mask creation.
  60  * Note that for technical reasons KCommonDecoration does not inherit KDecoration but
  61  * only provides the same API. If in rare cases you need to convert to KDecoration,
  62  * use the decoration() function.
  63  * See KDecoration documentation for all the wrapped functions.
  64  */
  65 class KWIN_EXPORT KCommonDecoration : public QObject, public KDecorationDefines
  66 {
  67     Q_OBJECT
  68
  69     public:
  70         KCommonDecoration(KDecorationBridge* bridge, KDecorationFactory* factory);
  71         virtual ~KCommonDecoration();
  72
  73         /**
  74          * Used to calculate the decoration layout. The basic layout looks like this:
  75          *
  76          * Window:
  77          *  _______________________________________________________________
  78          * |           LM_TitleEdgeTop                                     |
  79          * |_______________________________________________________________|
  80          * | LM_TitleEdgeLeft |   [title]              | LM_TitleEdgeRight |
  81          * |__________________|________________________|___________________|
  82          * |           LM_TitleEdgeBottom                                  |
  83          * |_______________________________________________________________|
  84          * | |                                                           | |
  85          * | |                                                           | |
  86          * | |                                                           | |
  87          * |LM_BorderLeft                                    LM_BorderRight|
  88          * |_|___________________________________________________________|_|
  89          * |           LM_BorderBottom                                     |
  90          * |_______________________________________________________________|
  91          *
  92          * Title:
  93          *  ___________________________________________________________________________________
  94          * | LM_ButtonMarginTop             |                |              LM_ButtonMarginTop |
  95          * |________________________________|                |_________________________________|
  96          * | [Buttons] | LM_TitleBorderLeft | LM_TitleHeight | LM_TitleBorderRight | [Buttons] |
  97          * |___________|____________________|________________|_____________________|___________|
  98          *
  99          * Buttons:
 100          *  _____________________________________________________________________________________________
 101          * | button | spacing | button | spacing | explicit spacer | spacing | ...    | spacing | button |
 102          * |________|_________|________|_________|_________________|_________|________|_________|________|
 103          *
 104          * @see layoutMetric()
 105          */
 106         enum LayoutMetric
 107         {
 108             LM_BorderLeft,
 109             LM_BorderRight,
 110             LM_BorderBottom,
 111             LM_TitleHeight,
 112             LM_TitleBorderLeft,
 113             LM_TitleBorderRight,
 114             LM_TitleEdgeLeft,
 115             LM_TitleEdgeRight,
 116             LM_TitleEdgeTop,
 117             LM_TitleEdgeBottom,
 118             LM_ButtonWidth,
 119             LM_ButtonHeight,
 120             LM_ButtonSpacing,
 121             LM_ExplicitButtonSpacer,
 122             LM_ButtonMarginTop
 123         };
 124
 125         enum DecorationBehaviour
 126         {
 127             DB_MenuClose, ///< Close window on double clicking the menu
 128             DB_WindowMask, ///< Set a mask on the window
 129             DB_ButtonHide  ///< Hide buttons when there is not enough space in the titlebar
 130         };
 131
 132         enum WindowCorner
 133         {
 134             WC_TopLeft,
 135             WC_TopRight,
 136             WC_BottomLeft,
 137             WC_BottomRight
 138         };
 139
 140         /**
 141          * The name of the decoration used in the decoration preview.
 142          */
 143         virtual QString visibleName() const = 0;
 144         /**
 145          * The default title button order on the left.
 146          * @see KDecoration::titleButtonsLeft()
 147          * @see KDecoration::titleButtonsRight()
 148          */
 149         virtual QString defaultButtonsLeft() const;
 150         /**
 151          * The default title button order on the left.
 152          * @see KDecoration::titleButtonsLeft()
 153          * @see KDecoration::titleButtonsRight()
 154          */
 155         virtual QString defaultButtonsRight() const;
 156
 157         /**
 158          * This controls whether some specific behaviour should be enabled or not.
 159          * @see DecorationBehaviour
 160          */
 161         virtual bool decorationBehaviour(DecorationBehaviour behaviour) const;
 162
 163         /**
 164          * This controls the layout of the decoration in various ways. It is
 165          * possible to have a different layout for different window states.
 166          * @param lm                 The layout element.
 167          * @param respectWindowState Whether window states should be taken into account or a "default" state should be assumed.
 168          * @param button             For LM_ButtonWidth and LM_ButtonHeight, the button.
 169          */
 170         virtual int layoutMetric(LayoutMetric lm, bool respectWindowState = true, const KCommonDecorationButton *button = 0) const;
 171
 172         /**
 173          * Create a new title bar button. KCommonDecoration takes care of memory management.
 174          * @return a pointer to the button, or 0 if the button should not be created.
 175          */
 176         virtual KCommonDecorationButton *createButton(ButtonType type) = 0;
 177
 178         /**
 179          * @return the mask for the specific window corner.
 180          */
 181         virtual QRegion cornerShape(WindowCorner corner);
 182
 183         /**
 184          * This updates the window mask using the information provided by
 185          * cornerShape(). Edges which are aligned to screen corners are not
 186          * shaped for better usability (remember to paint these areas in paintEvent(), too).
 187          * You normally don't want/need to reimplement updateWindowShape().
 188          * @see cornerShape()
 189          */
 190         virtual void updateWindowShape();
 191
 192         /**
 193          * Draw the window decoration.
 194          */
 195         virtual void paintEvent(QPaintEvent *e) = 0;
 196
 197         /**
 198          * This is used to update the painting of the title bar after the caption has been changed.
 199          * Reimplement for a more efficient implementation (default calls update() on the whole decoration).
 200          */
 201         virtual void updateCaption();
 202
 203         int buttonsLeftWidth() const;
 204         int buttonsRightWidth() const;
 205
 206         /**
 207          * TODO: remove?
 208          */
 209         void updateLayout() const;
 210         /**
 211          * Makes sure all buttons are repainted.
 212          */
 213         void updateButtons() const;
 214         /**
 215          * Manually call reset() on each button.
 216          */
 217         void resetButtons() const;
 218
 219         /**
 220          * Convenience method.
 221          * @returns true if the window type is NET::Toolbar, NET::Utility, or NET::Menu
 222          */
 223         bool isToolWindow() const;
 224         /**
 225          * Convenience method.
 226          * @returns the title rect.
 227          */
 228         QRect titleRect() const;
 229
 230     public:
 231         /**
 232          * Handles widget and layout creation, call the base implementation when subclassing this member.
 233          */
 234         virtual void init();
 235         /**
 236          * Handles SettingButtons, call the base implementation when subclassing this member.
 237          */
 238         virtual void reset( unsigned long changed );
 239         virtual void borders( int& left, int& right, int& top, int& bottom ) const;
 240         virtual void show();
 241         virtual void resize(const QSize& s);
 242         virtual QSize minimumSize() const;
 243         virtual void maximizeChange();
 244         virtual void desktopChange();
 245         virtual void shadeChange();
 246         virtual void iconChange();
 247         virtual void activeChange();
 248         virtual void captionChange();
 249     public Q_SLOTS:
 250         void keepAboveChange(bool above);
 251         void keepBelowChange(bool below);
 252         void slotMaximize();
 253         void slotShade();
 254         void slotKeepAbove();
 255         void slotKeepBelow();
 256         void menuButtonPressed();
 257         void menuButtonReleased();
 258     public:
 259         virtual Position mousePosition(const QPoint &point) const;
 260
 261         virtual bool eventFilter( QObject* o, QEvent* e );
 262         virtual void resizeEvent(QResizeEvent *e);
 263         virtual void mouseDoubleClickEvent(QMouseEvent *e);
 264         virtual void wheelEvent(QWheelEvent *e);
 265
 266         // *** wrap everything from KDecoration *** //
 267         // reimplementing from KDecoration (wrapped)
 268         virtual bool drawbound( const QRect& geom, bool clear );
 269         virtual bool windowDocked( Position side );
 270         // wrap everything KDecoration provides
 271         static const KDecorationOptions* options();
 272         bool isActive() const;
 273         bool isCloseable() const;
 274         bool isMaximizable() const;
 275         MaximizeMode maximizeMode() const;
 276         bool isMinimizable() const;
 277         bool providesContextHelp() const;
 278         int desktop() const;
 279         bool isOnAllDesktops() const; // convenience
 280         bool isModal() const;
 281         bool isShadeable() const;
 282         bool isShade() const;
 283         bool isSetShade() const;
 284         bool keepAbove() const;
 285         bool keepBelow() const;
 286         bool isMovable() const;
 287         bool isResizable() const;
 288         NET::WindowType windowType( unsigned long supported_types ) const;
 289         QIcon icon() const;
 290         QString caption() const;
 291         void showWindowMenu( const QRect &pos );
 292         void showWindowMenu( QPoint pos );
 293         void performWindowOperation( WindowOperation op );
 294         void setMask( const QRegion& reg, int mode = 0 );
 295         void clearMask(); // convenience
 296         bool isPreview() const;
 297         QRect geometry() const;
 298         QRect iconGeometry() const;
 299         QRegion unobscuredRegion( const QRegion& r ) const;
 300         WId windowId() const;
 301         int width() const; // convenience
 302         int height() const;  // convenience
 303         void processMousePressEvent( QMouseEvent* e );
 304     Q_SIGNALS:
 305         void keepAboveChanged( bool );
 306         void keepBelowChanged( bool );
 307     public:
 308         void setMainWidget( QWidget* );
 309         void createMainWidget( Qt::WFlags flags = 0 );
 310         QWidget* initialParentWidget() const;
 311         Qt::WFlags initialWFlags() const;
 312         QWidget* widget();
 313         const QWidget* widget() const;
 314         KDecorationFactory* factory() const;
 315         void grabXServer();
 316         void ungrabXServer();
 317     public Q_SLOTS:
 318         void closeWindow();
 319         void maximize( Qt::MouseButtons button );
 320         void maximize( MaximizeMode mode );
 321         void minimize();
 322         void showContextHelp();
 323         void setDesktop( int desktop );
 324         void toggleOnAllDesktops(); // convenience
 325         void titlebarDblClickOperation();
 326         void titlebarMouseWheelOperation( int delta );
 327         void setShade( bool set );
 328         void setKeepAbove( bool set );
 329         void setKeepBelow( bool set );
 330         // *** end of wrapping of everything from KDecoration *** //
 331     public:
 332         // access the KDecoration wrapper
 333         const KDecoration* decoration() const;
 334         KDecoration* decoration();
 335
 336     private:
 337         void resetLayout();
 338
 339         void moveWidget(int x, int y, QWidget *widget) const;
 340         void resizeWidget(int w, int h, QWidget *widget) const;
 341
 342         typedef QVector <KCommonDecorationButton*> ButtonContainer; ///< If the entry is 0, it's a spacer.
 343         int buttonContainerWidth(const ButtonContainer &btnContainer, bool countHidden = false) const;
 344         void addButtons(ButtonContainer &btnContainer, const QString& buttons, bool isLeft);
 345
 346         KCommonDecorationButton *m_button[NumButtons];
 347
 348         ButtonContainer m_buttonsLeft;
 349         ButtonContainer m_buttonsRight;
 350
 351         QWidget *m_previewWidget;
 352
 353         // button hiding for small windows
 354         void calcHiddenButtons();
 355         int btnHideMinWidth;
 356         int btnHideLastWidth;
 357
 358         bool closing; // for menu doubleclick closing...
 359
 360         KCommonDecorationWrapper* wrapper;
 361
 362         KCommonDecorationPrivate *d;
 363 };
 364
 365 class KWIN_EXPORT KCommonDecorationUnstable
 366     : public KCommonDecoration
 367     {
 368     Q_OBJECT
 369     public:
 370         KCommonDecorationUnstable(KDecorationBridge* bridge, KDecorationFactory* factory);
 371         virtual ~KCommonDecorationUnstable();
 372         virtual QList<QRect> shadowQuads( ShadowType type ) const;
 373         virtual double shadowOpacity( ShadowType type ) const;
 374         virtual double shadowBrightness( ShadowType type ) const;
 375         virtual double shadowSaturation( ShadowType type ) const;
 376         void repaintShadow();
 377         bool compositingActive() const;
 378         bool shadowsActive() const;
 379         double opacity() const;
 380     };
 381
 382 /**
 383  * Title bar buttons of KCommonDecoration need to inherit this class.
 384  */
 385 class KWIN_EXPORT KCommonDecorationButton : public QAbstractButton
 386 {
 387     Q_OBJECT
 388
 389     friend class KCommonDecoration;
 390
 391     public:
 392         KCommonDecorationButton(ButtonType type, KCommonDecoration *parent);
 393         virtual ~KCommonDecorationButton();
 394
 395         /**
 396          * These flags specify what has changed, e.g. the reason for a reset().
 397          */
 398         enum
 399         {
 400             ManualReset     = 1 << 0, ///< The button might want to do a full reset for some reason...
 401             SizeChange      = 1 << 1, ///< The button size changed @see setSize()
 402             ToggleChange    = 1 << 2, ///< The button toggle state has changed @see setToggleButton()
 403             StateChange     = 1 << 3, ///< The button has been set pressed or not... @see setOn()
 404             IconChange      = 1 << 4, ///< The window icon has been changed
 405             DecorationReset = 1 << 5  ///< E.g. when decoration colors have changed
 406         };
 407         /**
 408          * Initialize the button after size change etc.
 409          */
 410         virtual void reset(unsigned long changed) = 0;
 411         /**
 412          * @returns the KCommonDecoration the button belongs to.
 413          */
 414         KCommonDecoration *decoration() const;
 415         /**
 416          * @returns the button type.
 417          * @see ButtonType
 418          */
 419         ButtonType type() const;
 420
 421         /**
 422          * Whether the button is left of the titlebar or not.
 423          */
 424         bool isLeft() const;
 425
 426         /**
 427          * Set which mouse buttons the button should honor. Used e.g. to prevent accidental right mouse clicks.
 428          */
 429         void setRealizeButtons(int btns);
 430         /**
 431          * Set the button size.
 432          */
 433         void setSize(const QSize &s);
 434         /**
 435          * Set/update the button's tool tip
 436          */
 437         void setTipText(const QString &tip);
 438         /**
 439          * The mouse button that has been clicked last time.
 440          */
 441         Qt::MouseButtons lastMousePress() const { return m_lastMouse; }
 442
 443         QSize sizeHint() const;
 444
 445     protected:
 446         void setToggleButton(bool toggle);
 447         void setOn(bool on);
 448         void setLeft(bool left);
 449         void mousePressEvent(QMouseEvent *e);
 450         void mouseReleaseEvent(QMouseEvent *e);
 451
 452     private:
 453         KCommonDecoration *m_decoration;
 454         ButtonType m_type;
 455         int m_realizeButtons;
 456         QSize m_size;
 457         Qt::MouseButtons m_lastMouse;
 458
 459         bool m_isLeft;
 460
 461         KCommonDecorationButtonPrivate *d;
 462 };
 463
 464 /** @} */
 465
 466 #endif // KCOMMONDECORATION_H
 467
 468 // kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle;