1/*****************************************************************
2This file is part of the KDE project.
3
4Copyright (C) 2003 Lubos Lunak <l.lunak@kde.org>
5
6Permission is hereby granted, free of charge, to any person obtaining a
7copy of this software and associated documentation files (the "Software"),
8to deal in the Software without restriction, including without limitation
9the rights to use, copy, modify, merge, publish, distribute, sublicense,
10and/or sell copies of the Software, and to permit persons to whom the
11Software is furnished to do so, subject to the following conditions:
12
13The above copyright notice and this permission notice shall be included in
14all copies or substantial portions of the Software.
15
16THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22DEALINGS IN THE SOFTWARE.
23******************************************************************/
24
25#ifndef KDECORATION_H
26#define KDECORATION_H
27
28#include <kwinglobals.h>
29
30#include <QtGui/QColor>
31#include <QtGui/QFont>
32#include <QObject>
33#include <QtGui/QIcon>
34#include <netwm_def.h>
35#include <QtGui/QMouseEvent>
36
37#define KWIN_DECORATION_API_VERSION 1
38
39/**
40 * Defines the class to be used for decoration factory.
41 * The class must be namespace complete.
42 * E.g. KWIN_EFFECT( Oxygen::Factory )
43 **/
44#define KWIN_DECORATION( classname ) \
45 extern "C" { \
46 KWIN_EXPORT KDecorationFactory* create_factory() { return new classname(); } \
47 KWIN_EXPORT int decoration_version() { return KWIN_DECORATION_API_VERSION; } \
48 }
49
50#define KWIN_DECORATION_BRIDGE_API_VERSION 1
51extern "C" {
52 int decoration_bridge_version();
53}
54
55class KConfig;
56
57/** @defgroup kdecoration KWin decorations library */
58
59/** @addtogroup kdecoration */
60/** @{ */
61
62class KDecorationOptionsPrivate;
63class KDecorationBridge;
64class KDecorationPrivate;
65class KDecorationFactory;
66
67/**
68 * This class provides a namespace for all decoration related classes.
69 * All shared types are defined here.
70 */
71class KWIN_EXPORT KDecorationDefines
72{
73public:
74 /**
75 * These values represent positions inside an area
76 */
77 enum Position {
78 // without prefix, they'd conflict with Qt::TopLeftCorner etc. :(
79 PositionCenter = 0x00,
80 PositionLeft = 0x01,
81 PositionRight = 0x02,
82 PositionTop = 0x04,
83 PositionBottom = 0x08,
84 PositionTopLeft = PositionLeft | PositionTop,
85 PositionTopRight = PositionRight | PositionTop,
86 PositionBottomLeft = PositionLeft | PositionBottom,
87 PositionBottomRight = PositionRight | PositionBottom
88 };
89 /**
90 * Maximize mode. These values specify how a window is maximized.
91 */
92 // these values are written to session files, don't change the order
93 enum MaximizeMode {
94 MaximizeRestore = 0, ///< The window is not maximized in any direction.
95 MaximizeVertical = 1, ///< The window is maximized vertically.
96 MaximizeHorizontal = 2, ///< The window is maximized horizontally.
97 /// Equal to @p MaximizeVertical | @p MaximizeHorizontal
98 MaximizeFull = MaximizeVertical | MaximizeHorizontal
99 };
100
101 enum QuickTileFlag {
102 QuickTileNone = 0,
103 QuickTileLeft = 1,
104 QuickTileRight = 1<<1,
105 QuickTileTop = 1<<2,
106 QuickTileBottom = 1<<3,
107 QuickTileHorizontal = QuickTileLeft|QuickTileRight,
108 QuickTileVertical = QuickTileTop|QuickTileBottom,
109 QuickTileMaximize = QuickTileLeft|QuickTileRight|QuickTileTop|QuickTileBottom
110 };
111
112 Q_DECLARE_FLAGS(QuickTileMode, QuickTileFlag)
113
114 enum WindowOperation {
115 MaximizeOp = 5000,
116 RestoreOp,
117 MinimizeOp,
118 MoveOp,
119 UnrestrictedMoveOp,
120 ResizeOp,
121 UnrestrictedResizeOp,
122 CloseOp,
123 OnAllDesktopsOp,
124 ShadeOp,
125 KeepAboveOp,
126 KeepBelowOp,
127 OperationsOp,
128 WindowRulesOp,
129 ToggleStoreSettingsOp = WindowRulesOp, ///< @obsolete
130 HMaximizeOp,
131 VMaximizeOp,
132 LowerOp,
133 FullScreenOp,
134 NoBorderOp,
135 NoOp,
136 SetupWindowShortcutOp,
137 ApplicationRulesOp,
138 RemoveTabFromGroupOp, // Remove from group
139 CloseTabGroupOp, // Close the group
140 ActivateNextTabOp, // Move left in the group
141 ActivatePreviousTabOp, // Move right in the group
142 ///< @deprecated, tiling got removed in 4.10
143 ToggleClientTiledStateOp, // put a floating client into tiling
144 TabDragOp,
145
146 //BEGIN ABI stability stuff
147 // NOTICE for ABI stability
148 // TODO remove with mandatory version tagging fo 4.9.x or 4.10
149 /** @deprecated ABI compatibility only - don't use */
150 RemoveClientFromGroupOp = RemoveTabFromGroupOp, // Remove from group
151 CloseClientGroupOp = CloseTabGroupOp, // Close the group
152 MoveClientInGroupLeftOp = ActivateNextTabOp, // Move left in the group
153 MoveClientInGroupRightOp = ActivatePreviousTabOp // Move right in the group
154 //END ABI stability stuff
155 };
156 /**
157 * Basic color types that should be recognized by all decoration styles.
158 * Decorations are not required to implement all the colors, but for the ones that
159 * are implemented the color setting for them should be obeyed.
160 */
161 enum ColorType {
162 ColorTitleBar, ///< The color for the titlebar
163 ColorTitleBlend, ///< The blend color for the titlebar
164 ColorFont, ///< The titlebar text color
165 ColorButtonBg, ///< The color to use for the titlebar buttons
166 ColorFrame, ///< The color for the window frame (border)
167 ColorHandle, ///< The color for the resize handle
168 NUM_COLORS ///< @internal This value may change, do not use
169 };
170
171 /**
172 * These flags specify which settings changed when rereading settings.
173 * Each setting in class KDecorationOptions specifies its matching flag.
174 */
175 enum {
176 SettingDecoration = 1 << 0, ///< The decoration was changed
177 SettingColors = 1 << 1, ///< The color palette was changed
178 SettingFont = 1 << 2, ///< The titlebar font was changed
179 SettingButtons = 1 << 3, ///< The button layout was changed
180 SettingTooltips = 1 << 4, ///< The tooltip setting was changed
181 SettingBorder = 1 << 5, ///< The border size setting was changed
182 SettingCompositing = 1 << 6 ///< Compositing settings was changed
183 };
184
185 /**
186 * Border size. KDecorationOptions::preferredBorderSize() returns
187 * one of these values.
188 */
189 enum BorderSize {
190 BorderTiny, ///< Minimal borders
191 BorderNormal, ///< Standard size borders, the default setting
192 BorderLarge, ///< Larger borders
193 BorderVeryLarge, ///< Very large borders
194 BorderHuge, ///< Huge borders
195 BorderVeryHuge, ///< Very huge borders
196 BorderOversized, ///< Oversized borders
197 BorderNoSides, ///< No borders on sides @since 4.11
198 BorderNone, ///< No borders except title @since 4.11
199 BordersCount ///< @internal
200 };
201
202 /**
203 * Used to find out which features the decoration supports.
204 * @see KDecorationFactory::supports()
205 */
206 enum Ability {
207 // announce
208 AbilityAnnounceButtons = 0, ///< decoration supports AbilityButton* values (always use)
209 AbilityAnnounceColors = 1, ///< decoration supports AbilityColor* values (always use), @deprecated @todo remove KDE5
210 // buttons
211 AbilityButtonMenu = 1000, ///< decoration supports the window menu button
212 AbilityButtonOnAllDesktops = 1001, ///< decoration supports the on all desktops button
213 AbilityButtonSpacer = 1002, ///< decoration supports inserting spacers between buttons
214 AbilityButtonHelp = 1003, ///< decoration supports what's this help button
215 AbilityButtonMinimize = 1004, ///< decoration supports a minimize button
216 AbilityButtonMaximize = 1005, ///< decoration supports a maximize button
217 AbilityButtonClose = 1006, ///< decoration supports a close button
218 AbilityButtonAboveOthers = 1007, ///< decoration supports an above button
219 AbilityButtonBelowOthers = 1008, ///< decoration supports a below button
220 AbilityButtonShade = 1009, ///< decoration supports a shade button
221 AbilityButtonResize = 1010, ///< decoration supports a resize button
222 AbilityButtonApplicationMenu = 1011, ///< decoration supports the application menu button
223 // colors
224 AbilityColorTitleBack = 2000, ///< decoration supports titlebar background color, @deprecated @todo remove KDE5
225 ABILITYCOLOR_FIRST = AbilityColorTitleBack, ///< @internal, @deprecated @todo remove KDE5
226 AbilityColorTitleFore = 2001, ///< decoration supports titlebar foreground color, @deprecated @todo remove KDE5
227 AbilityColorTitleBlend = 2002, ///< decoration supports second titlebar background color, @deprecated @todo remove KDE5
228 AbilityColorFrame = 2010, ///< decoration supports frame color, @deprecated @todo remove KDE5
229 AbilityColorHandle = 2011, ///< decoration supports resize handle color, @deprecated @todo remove KDE5
230 AbilityColorButtonBack = 2020, ///< decoration supports button background color, @deprecated @todo remove KDE5
231 AbilityColorButtonFore = 2021, ///< decoration supports button foreground color, @deprecated @todo remove KDE5
232 ABILITYCOLOR_END, ///< @internal, @deprecated @todo remove KDE5
233 // compositing
234 AbilityProvidesShadow = 3000, ///< The decoration draws its own shadows.
235 /// @since 4.3
236 AbilityUsesAlphaChannel = 3001, ///< The decoration isn't clipped to the mask when compositing is enabled.
237 /// The mask is still used to define the input region and the blurred
238 /// region, when the blur plugin is enabled.
239 /// @since 4.3
240 AbilityExtendIntoClientArea = 3002, ///< The decoration respects transparentRect()
241 /// @since 4.4
242 AbilityUsesBlurBehind = 3003, ///< The decoration wants the background to be blurred, when the blur plugin is enabled.
243 /// @since 4.6
244 AbilityAnnounceAlphaChannel = 4004, ///< The decoration can tell whether it currently uses an alpha channel or not. Requires AbilityUsesAlphaChannel.
245 /// @since 4.10
246 // Tabbing
247 AbilityTabbing = 4000, ///< The decoration supports tabbing
248 // TODO colors for individual button types
249 ABILITY_DUMMY = 10000000,
250
251 //BEGIN ABI stability stuff
252 // NOTICE for ABI stability
253 // TODO remove with mandatory version tagging fo 4.9.x or 4.10
254 /** @deprecated ABI compatibility only - don't use */
255 AbilityClientGrouping = AbilityTabbing
256 //END ABI stability stuff
257 };
258
259 enum Requirement { REQUIREMENT_DUMMY = 1000000 };
260
261 /**
262 * Regions that can be returned by KDecorationUnstable::region().
263 */
264 enum Region {
265 /**
266 * This is an invisible input region that can be used to expand the
267 * borders by an invisible amount, both inside and outside the
268 * decoration. The intended use case is to provide an active border
269 * area that's larger than the visible border.
270 *
271 * The mousePosition() implementation must return correct values
272 * for the pixels inside this region.
273 *
274 * Note that mouse events that occur within this region are not
275 * forwarded to the decoration. This may change in the future.
276 *
277 * @since 4.8
278 */
279 ExtendedBorderRegion
280 };
281
282 /**
283 * Returns the mimeType used to drag and drop clientGroupItems
284 */
285 //BEGIN ABI stability stuff
286 // NOTICE for ABI stability
287 // TODO remove with mandatory version tagging fo 4.9.x or 4.10
288 /** @deprecated ABI compatibility only - don't use */
289 static QString clientGroupItemDragMimeType() { return tabDragMimeType(); }
290 //END ABI stability stuff
291 static QString tabDragMimeType();
292
293};
294
295//BEGIN ABI stability stuff
296// NOTICE for ABI stability
297// TODO remove with mandatory version tagging fo 4.9.x or 4.10
298/** @deprecated ABI compatibility only - don't use */
299class KWIN_EXPORT ClientGroupItem
300{
301public:
302 ClientGroupItem(QString t, QIcon i) {
303 title_ = t;
304 icon_ = i;
305 }
306 inline QIcon icon() const {
307 return icon_;
308 }
309 inline QString title() const {
310 return title_;
311 }
312private:
313 QString title_;
314 QIcon icon_;
315};
316//END ABI stability stuff
317
318class KDecorationProvides
319 : public KDecorationDefines
320{
321public:
322 virtual ~KDecorationProvides() {}
323 virtual bool provides(Requirement req) = 0;
324};
325
326/**
327 * This class holds various configuration settings for the decoration.
328 * It is accessible from the decorations either as KDecoration::options()
329 * or KDecorationFactory::options().
330 */
331class KWIN_EXPORT KDecorationOptions : public KDecorationDefines
332{
333public:
334 KDecorationOptions();
335 virtual ~KDecorationOptions();
336 /**
337 * Call to update settings when the config changes. Return value is
338 * a combination of Setting* (SettingColors, etc.) that have changed.
339 * @since 4.0.1
340 */
341 unsigned long updateSettings(KConfig* config);
342 /**
343 * Returns the color that should be used for the given part of the decoration.
344 * The changed flags for this setting is SettingColors.
345 *
346 * @param type The requested color type.
347 * @param active Whether the color should be for active or inactive windows.
348 */
349 QColor color(ColorType type, bool active = true) const;
350 /**
351 * Returns a palette using the given decoration color as the background.
352 * The changed flags for this setting is SettingColors.
353 *
354 * @param type The requested color type.
355 * @param active Whether to return the color for active or inactive windows.
356 */
357 QPalette palette(ColorType type, bool active = true) const;
358 /**
359 * Returns the active or inactive decoration font.
360 * The changed flags for this setting is SettingFont.
361 *
362 * @param active Whether to return the color for active or inactive windows.
363 * @param small If @a true, returns a font that's suitable for tool windows.
364 */
365 QFont font(bool active = true, bool small = false) const;
366 /**
367 * Returns @a true if the style should use custom button positions
368 * The changed flags for this setting is SettingButtons.
369 *
370 * @see titleButtonsLeft
371 * @see titleButtonsRight
372 */
373 bool customButtonPositions() const;
374 /**
375 * If customButtonPositions() returns true, titleButtonsLeft
376 * returns which buttons should be on the left side of the titlebar from left
377 * to right. Characters in the returned string have this meaning :
378 * @li 'N' application menu button
379 * @li 'M' window menu button
380 * @li 'S' on_all_desktops button
381 * @li 'H' quickhelp button
382 * @li 'I' minimize ( iconify ) button
383 * @li 'A' maximize button
384 * @li 'X' close button
385 * @li 'F' keep_above_others button
386 * @li 'B' keep_below_others button
387 * @li 'L' shade button
388 * @li 'R' resize button
389 * @li '_' spacer
390 *
391 * The default ( which is also returned if customButtonPositions returns false )
392 * is "MS".
393 * Unknown buttons in the returned string must be ignored.
394 * The changed flags for this setting is SettingButtons.
395 */
396 QString titleButtonsLeft() const;
397 /**
398 * Returns the default left button sequence
399 */
400 static QString defaultTitleButtonsLeft();
401 /**
402 * If customButtonPositions() returns true, titleButtonsRight
403 * returns which buttons should be on the right side of the titlebar from left
404 * to right. Characters in the return string have the same meaning like
405 * in titleButtonsLeft().
406 *
407 * The default ( which is also returned if customButtonPositions returns false )
408 * is "HIA__X".
409 * Unknown buttons in the returned string must be ignored.
410 * The changed flags for this setting is SettingButtons.
411 */
412 QString titleButtonsRight() const;
413 /**
414 * Returns the default right button sequence.
415 */
416 static QString defaultTitleButtonsRight();
417 /**
418 * @returns true if the style should use tooltips for window buttons
419 * The changed flags for this setting is SettingTooltips.
420 */
421 bool showTooltips() const;
422
423 /**
424 * The preferred border size selected by the user, e.g. for accessibility
425 * reasons, or when using high resolution displays. It's up to the decoration
426 * to decide which borders or if any borders at all will obey this setting.
427 * It is guaranteed that the returned value will be one of those
428 * returned by KDecorationFactory::borderSizes(), so if that one hasn't been
429 * reimplemented, BorderNormal is always returned.
430 * The changed flags for this setting is SettingBorder.
431 * @param factory the decoration factory used
432 */
433 BorderSize preferredBorderSize(KDecorationFactory* factory) const;
434
435 /**
436 * This functions returns false
437 * @deprecated
438 */
439 bool moveResizeMaximizedWindows() const;
440
441 /**
442 * @internal
443 */
444 WindowOperation operationMaxButtonClick(Qt::MouseButtons button) const;
445
446 /**
447 * @internal
448 */
449 virtual unsigned long updateSettings() = 0; // returns SettingXYZ mask
450
451protected:
452 /** @internal */
453 void setOpMaxButtonLeftClick(WindowOperation op);
454 /** @internal */
455 void setOpMaxButtonRightClick(WindowOperation op);
456 /** @internal */
457 void setOpMaxButtonMiddleClick(WindowOperation op);
458 /** @internal */
459 void setBorderSize(BorderSize bs);
460 /** @internal */
461 void setCustomButtonPositions(bool b);
462 /** @internal */
463 void setTitleButtonsLeft(const QString& b);
464 /** @internal */
465 void setTitleButtonsRight(const QString& b);
466private:
467 /**
468 * @internal
469 */
470 KDecorationOptionsPrivate* d;
471};
472
473
474/**
475 * This is the base class for a decoration object. It provides functions
476 * that give various information about the decorated window, and also
477 * provides pure virtual functions for controlling the decoration that
478 * every decoration should implement.
479 */
480class KWIN_EXPORT KDecoration
481 : public QObject, public KDecorationDefines
482{
483 Q_OBJECT
484public:
485 /**
486 * Constructs a KDecoration object. Both the arguments are passed from
487 * KDecorationFactory. Note that the initialization code of the decoration
488 * should be done in the init() method.
489 */
490 KDecoration(KDecorationBridge* bridge, KDecorationFactory* factory);
491 /**
492 * Destroys the KDecoration.
493 */
494 virtual ~KDecoration();
495
496 // requests from decoration
497
498 /**
499 * Returns the KDecorationOptions object, which is used to access
500 * configuration settings for the decoration.
501 */
502 static const KDecorationOptions* options();
503 /**
504 * Returns @a true if the decorated window is currently active.
505 */
506 bool isActive() const;
507 /**
508 * Returns @a true if the decoration window can be closed by the user.
509 */
510 bool isCloseable() const;
511 /**
512 * Returns @a true if the decorated window can be maximized.
513 */
514 bool isMaximizable() const;
515 /**
516 * Returns the current maximization mode of the decorated window.
517 * Note that only fully maximized windows should be treated
518 * as "maximized" (e.g. if the maximize button has only two states).
519 */
520 MaximizeMode maximizeMode() const;
521 /**
522 * Returns @a true if the decorated window can be minimized by the user.
523 */
524
525 /**
526 * Returns the current quicktiling mode of the decorated window.
527 * (window is places into one of the corners or edges)
528 */
529 QuickTileMode quickTileMode() const;
530
531 bool isMinimizable() const;
532 /**
533 * Return @a true if the decorated window can show context help
534 * (i.e. the decoration should provide the context help button).
535 */
536 bool providesContextHelp() const;
537 /**
538 * Returns the number of the virtual desktop the decorated window
539 * is currently on (including NET::OnAllDesktops for being on all
540 * desktops).
541 */
542 int desktop() const;
543 /**
544 * Convenience function that returns @a true if the window is on all
545 * virtual desktops.
546 */
547 bool isOnAllDesktops() const; // convenience
548 /**
549 * Returns @a true if the decoration window is modal (usually a modal dialog).
550 */
551 bool isModal() const;
552 /**
553 * Returns @a true if the decorated window can be shaded.
554 */
555 bool isShadeable() const;
556 /**
557 * Returns @a true if the decorated window is currently shaded.
558 * If the window is e.g. hover unshaded, it's not considered to be shaded.
559 * This function should not be used for the shade titlebar button, use
560 * @ref isSetShade() instead.
561 *
562 * @see isSetShade
563 */
564 bool isShade() const;
565 /**
566 * Returns @a true if the decorated window was set to be shaded. This function
567 * returns also true if the window is e.g. hover unshaded, so it doesn't
568 * always correspond to the actual window state.
569 *
570 * @see isShade
571 */
572 bool isSetShade() const;
573 /**
574 * Returns @a true if the decorated window should be kept above other windows.
575 */
576 bool keepAbove() const;
577 /**
578 * Returns @a true if the decorated window should be kept below other windows.
579 */
580 bool keepBelow() const;
581 /**
582 * Returns @a true if the decorated window can be moved by the user.
583 */
584 bool isMovable() const;
585 /**
586 * Returns @a true if the decorated window can be resized by the user.
587 */
588 bool isResizable() const;
589 /**
590 * This function returns the window type of the decorated window.
591 * The argument to this function is a mask of all window types
592 * the decoration knows about (as the list of valid window types
593 * is extended over time, and fallback types are specified in order
594 * to support older code). For a description of all window types,
595 * see the definition of the NET::WindowType type. Note that
596 * some window types never have decorated windows.
597 *
598 * An example of usage:
599 * @code
600 * const unsigned long supported_types = NET::NormalMask | NET::DesktopMask
601 * | NET::DockMask | NET::ToolbarMask | NET::MenuMask | NET::DialogMask
602 * | NET::OverrideMask | NET::TopMenuMask | NET::UtilityMask | NET::SplashMask;
603 *
604 * NET::WindowType type = windowType( supported_types );
605 *
606 * if ( type == NET::Utility || type == NET::Menu || type == NET::Toolbar )
607 * // ... use smaller decorations for tool window types
608 * else
609 * // ... use normal decorations
610 * @endcode
611 */
612 NET::WindowType windowType(unsigned long supported_types) const;
613 /**
614 * Returns an icon set with the decorated window's icon.
615 */
616 QIcon icon() const;
617 /**
618 * Returns the decorated window's caption that should be shown in the titlebar.
619 */
620 QString caption() const;
621 /**
622 * This function invokes the window operations menu.
623 * \param pos specifies the place on the screen where the menu should
624 * show up. The menu pops up at the bottom-left corner of the specified
625 * rectangle, unless there is no space, in which case the menu is
626 * displayed above the rectangle.
627 *
628 * \note Decorations that enable a double-click operation for the menu
629 * button must ensure to call \a showWindowMenu() with the \a pos
630 * rectangle set to the menu button geometry.
631 * IMPORTANT: As a result of this function, the decoration object that
632 * called it may be destroyed after the function returns. This means
633 * that the decoration object must either return immediately after
634 * calling showWindowMenu(), or it must use
635 * KDecorationFactory::exists() to check it's still valid. For example,
636 * the code handling clicks on the menu button should look similarly
637 * like this:
638 *
639 * \code
640 * KDecorationFactory* f = factory(); // needs to be saved before
641 * showWindowMenu( button[MenuButton]->mapToGlobal( menuPoint ));
642 * if ( !f->exists( this )) // destroyed, return immediately
643 * return;
644 * button[MenuButton]->setDown(false);
645 * \endcode
646 */
647 void showWindowMenu(const QRect &pos);
648
649 /**
650 * Overloaded version of the above.
651 */
652 void showWindowMenu(QPoint pos);
653 /**
654 * show application menu at p
655 */
656 void showApplicationMenu(const QPoint& p);
657 /**
658 * Returns @a true if menu available for client
659 */
660 bool menuAvailable() const;
661 /**
662 * This function performs the given window operation. This function may destroy
663 * the current decoration object, just like showWindowMenu().
664 */
665 void performWindowOperation(WindowOperation op);
666 /**
667 * If the decoration is non-rectangular, this function needs to be called
668 * to set the shape of the decoration.
669 *
670 * @param reg The shape of the decoration.
671 * @param mode The X11 values Unsorted, YSorted, YXSorted and YXBanded that specify
672 * the sorting of the rectangles, default value is Unsorted.
673 */
674 void setMask(const QRegion& reg, int mode = 0);
675 /**
676 * This convenience function resets the shape mask.
677 */
678 void clearMask(); // convenience
679 /**
680 * If this function returns @a true, the decorated window is used as a preview
681 * e.g. in the configuration module. In such case, the decoration can e.g.
682 * show some information in the window area.
683 */
684 bool isPreview() const;
685 /**
686 * Returns the geometry of the decoration.
687 */
688 QRect geometry() const;
689 /**
690 * Returns the icon geometry for the window, i.e. the geometry of the taskbar
691 * entry. This is used mainly for window minimize animations. Note that
692 * the geometry may be null.
693 */
694 QRect iconGeometry() const;
695 /**
696 * Returns the intersection of the given region with the region left
697 * unobscured by the windows stacked above the current one. You can use
698 * this function to, for example, try to keep the titlebar visible if
699 * there is a hole available. The region returned is in the coordinate
700 * space of the decoration.
701 * @param r The region you want to check for holes
702 */
703 QRegion unobscuredRegion(const QRegion& r) const;
704 /**
705 * Returns the handle of the window that is being decorated. It is possible
706 * the returned value will be 0.
707 * IMPORTANT: This function is meant for special purposes, and it
708 * usually should not be used. The main purpose is finding out additional
709 * information about the window's state. Also note that different kinds
710 * of windows are decorated: Toplevel windows managed by the window manager,
711 * test window in the window manager decoration module, and possibly also
712 * other cases.
713 * Careless abuse of this function will usually sooner or later lead
714 * to problems.
715 */
716 WId windowId() const;
717 /**
718 * Convenience function that returns the width of the decoration.
719 */
720 int width() const; // convenience
721 /**
722 * Convenience function that returns the height of the decoration.
723 */
724 int height() const; // convenience
725 /**
726 * Returns the rectangle within the window frame that should be transparent.
727 * Usually this rectangle is the same as the client area, and it is never
728 * larger.
729 *
730 * If the client has requested that the window frame is extended into the
731 * client area, this rectangle is smaller than the client area.
732 *
733 * If the window frame should cover the whole client area, a null rectangle
734 * is returned.
735 *
736 * @since 4.4
737 */
738 QRect transparentRect() const;
739 /**
740 * This function is the default handler for mouse events. All mouse events
741 * that are not handled by the decoration itself should be passed to it
742 * in order to make work operations like window resizing by dragging borders etc.
743 */
744 void processMousePressEvent(QMouseEvent* e);
745
746 /**
747 * Whether the alpha channel is currently enabled. The value of this property is
748 * only relevant in case the decoration provides the AbilityAnnounceAlphaChannel.
749 *
750 * The compositor can make use of this information to optimize the rendering of the
751 * decoration.
752 *
753 * The default value of this property is @c false. That means if a decoration wants to make
754 * use alpha channel it has to call setAlphaEnabled with @c true.
755 *
756 * @see setAlphaEnabled
757 * @see alphaEnabledChanged
758 * @since 4.10
759 **/
760 bool isAlphaEnabled() const;
761
762 // requests to decoration
763
764 /**
765 * This function is called immediately after the decoration object is created.
766 * Due to some technical reasons, initialization should be done here
767 * instead of in the constructor.
768 */
769 virtual void init() = 0; // called once right after created
770
771 /**
772 * This function should return mouse cursor position in the decoration.
773 * Positions at the edge will result in window resizing with mouse button
774 * pressed, center position will result in moving.
775 */
776 virtual Position mousePosition(const QPoint& p) const = 0;
777
778 /**
779 * This function should return the distance from each window side to the inner
780 * window. The sizes may depend on the state of the decorated window, such as
781 * whether it's shaded. Decorations often turn off their bottom border when the
782 * window is shaded, and turn off their left/right/bottom borders when
783 * the window is maximized and moving and resizing of maximized windows is disabled.
784 * This function mustn't do any repaints or resizes. Also, if the sizes returned
785 * by this function don't match the real values, this may result in drawing errors
786 * or other problems.
787 *
788 * @see KDecorationOptions::moveResizeMaximizedWindows()
789 */
790 // mustn't do any repaints, resizes or anything like that
791 virtual void borders(int& left, int& right, int& top, int& bottom) const = 0;
792 /**
793 * This method is called by kwin when the style should resize the decoration window.
794 * The usual implementation is to resize the main widget of the decoration to the
795 * given size.
796 *
797 * @param s Specifies the new size of the decoration window.
798 */
799 virtual void resize(const QSize& s) = 0;
800 /**
801 * This function should return the minimum required size for the decoration.
802 * Note that the returned size shouldn't be too large, because it will be
803 * used to keep the decorated window at least as large.
804 */
805 virtual QSize minimumSize() const = 0;
806
807public Q_SLOTS:
808 /**
809 * This function is called whenever the window either becomes or stops being active.
810 * Use isActive() to find out the current state.
811 */
812 virtual void activeChange() = 0;
813 /**
814 * This function is called whenever the caption changes. Use caption() to get it.
815 */
816 virtual void captionChange() = 0;
817 /**
818 * This function is called whenever the window icon changes. Use icon() to get it.
819 */
820 virtual void iconChange() = 0;
821 /**
822 * This function is called whenever the maximalization state of the window changes.
823 * Use maximizeMode() to get the current state.
824 */
825 virtual void maximizeChange() = 0;
826 /**
827 * This function is called whenever the desktop for the window changes. Use
828 * desktop() or isOnAllDesktops() to find out the current desktop
829 * on which the window is.
830 */
831 virtual void desktopChange() = 0;
832 /**
833 * This function is called whenever the window is shaded or unshaded. Use
834 * isShade() to get the current state.
835 */
836 virtual void shadeChange() = 0;
837
838Q_SIGNALS:
839 /**
840 * This signal is emitted whenever the window's keep-above state changes.
841 */
842 void keepAboveChanged(bool);
843 /**
844 * This signal is emitted whenever the window's keep-below state changes.
845 */
846 void keepBelowChanged(bool);
847
848 /**
849 * This signal is emitted whenever application menu is closed
850 * Application menu button may need to be modified on this signal
851 */
852 void menuHidden();
853 /**
854 * This signal is emitted whenever application want to show it menu
855 */
856 void showRequest();
857 /**
858 * This signal is emitted whenever application menu becomes available
859 */
860 void appMenuAvailable();
861 /**
862 * This signal is emitted whenever application menu becomes unavailable
863 */
864 void appMenuUnavailable();
865
866 /**
867 * This signal is emitted whenever the decoration changes it's alpha enabled
868 * change. Only relevant in case the decoration provides AbilityAnnounceAlphaChannel.
869 *
870 * @param enabled The new state of alpha channel usage
871 * @see setAlphaEnabled
872 * @see isAlphaEnabled
873 * @since 4.10
874 **/
875 void alphaEnabledChanged(bool enabled);
876
877public:
878 /**
879 * This method is not any more invoked from KWin core since version 4.8.
880 * There is no need to implement it.
881 *
882 * @param geom The geometry at this the bound should be drawn
883 * @param clear @a true if the bound should be cleared (when doing the usual XOR
884 * painting this argument can be simply ignored)
885 *
886 * @see geometry()
887 * @deprecated
888 */
889 virtual bool drawbound(const QRect& geom, bool clear);
890 /**
891 * @internal Reserved.
892 */
893 // TODO position will need also values for top+left+bottom etc. docking ?
894 virtual bool windowDocked(Position side);
895 /**
896 * This function is called to reset the decoration on settings changes.
897 * It is usually invoked by calling KDecorationFactory::resetDecorations().
898 *
899 * @param changed Specifies which settings were changed, given by the SettingXXX masks
900 */
901 virtual void reset(unsigned long changed);
902
903 // special
904
905 /**
906 * This should be the first function called in init() to specify
907 * the main widget of the decoration. The widget should be created
908 * with parent specified by initialParentWidget() and flags
909 * specified by initialWFlags().
910 */
911 void setMainWidget(QWidget*);
912 /**
913 * Convenience functions that creates and sets a main widget as necessary.
914 * In such case, it's usually needed to install an event filter
915 * on the main widget to receive important events on it.
916 *
917 * @param flags Additional widget flags for the main widget. Note that only
918 * flags that affect widget drawing are allowed. Window type flags
919 * like WX11BypassWM or WStyle_NoBorder are forbidden.
920 */
921 void createMainWidget(Qt::WFlags flags = 0);
922 /**
923 * The parent widget that should be used for the main widget.
924 */
925 QWidget* initialParentWidget() const;
926 /**
927 * The flags that should be used when creating the main widget.
928 * It is possible to add more flags when creating the main widget, but only flags
929 * that affect widget drawing are allowed. Window type flags like WX11BypassWM
930 * or WStyle_NoBorder are forbidden.
931 */
932 Qt::WFlags initialWFlags() const;
933 /**
934 * Returns the main widget for the decoration.
935 */
936 QWidget* widget();
937 /**
938 * Returns the main widget for the decoration.
939 */
940 const QWidget* widget() const;
941 /**
942 * Returns the factory that created this decoration.
943 */
944 KDecorationFactory* factory() const;
945 /**
946 * Performs X server grab. It is safe to call it several times in a row.
947 */
948 void grabXServer();
949 /**
950 * Ungrabs X server (if the number of ungrab attempts matches the number of grab attempts).
951 */
952 void ungrabXServer();
953
954public: // invokables; runtime resolution
955 /**
956 * reimplement this invokable to signal the core where the titlebar is (usually PositionTop)
957 */
958 Q_INVOKABLE KDecorationDefines::Position titlebarPosition();
959
960public Q_SLOTS:
961 // requests from decoration
962
963 /**
964 * This function can be called by the decoration to request
965 * closing of the decorated window. Note that closing the window
966 * also involves destroying the decoration.
967 * IMPORTANT: This function may destroy the current decoration object,
968 * just like showWindowMenu().
969 */
970 void closeWindow();
971 /**
972 * Changes the maximize mode of the decorated window. This function should
973 * be preferred to the other maximize() overload for reacting on clicks
974 * on the maximize titlebar button.
975 */
976 void maximize(Qt::MouseButtons button);
977 /**
978 * Set the maximize mode of the decorated window.
979 * @param mode The maximization mode to be set.
980 */
981 void maximize(MaximizeMode mode);
982 /**
983 * Minimize the decorated window.
984 */
985 void minimize();
986 /**
987 * Start showing context help in the window (i.e. the mouse will enter
988 * the what's this mode).
989 */
990 void showContextHelp();
991 /**
992 * Moves the window to the given desktop. Use NET::OnAllDesktops for making
993 * the window appear on all desktops.
994 */
995 void setDesktop(int desktop);
996 /**
997 * This function toggles the on-all-desktops state of the decorated window.
998 */
999 void toggleOnAllDesktops(); // convenience
1000 /**
1001 * This function performs the operation configured as titlebar double click
1002 * operation.
1003 */
1004 void titlebarDblClickOperation();
1005 /**
1006 * This function performs the operation configured as titlebar wheel mouse
1007 * operation.
1008 * @param delta the mouse wheel delta
1009 */
1010 void titlebarMouseWheelOperation(int delta);
1011 /**
1012 * Shades or unshades the decorated window.
1013 * @param set Whether the window should be shaded
1014 */
1015 void setShade(bool set);
1016 /**
1017 * Sets or reset keeping this window above others.
1018 * @param set Whether to keep the window above others
1019 */
1020 void setKeepAbove(bool set);
1021 /**
1022 * Sets or reset keeping this window below others.
1023 * @param set Whether to keep the window below others
1024 */
1025 void setKeepBelow(bool set);
1026 /**
1027 * @internal
1028 * TODO KF5: remove me
1029 */
1030 void emitKeepAboveChanged(bool above);
1031 /**
1032 * @internal
1033 * TODO KF5: remove me
1034 */
1035 void emitKeepBelowChanged(bool below);
1036
1037protected Q_SLOTS:
1038 /**
1039 * A decoration providing AbilityAnnounceAlphaChannel can use this method to enable/disable the
1040 * use of alpha channel. This is useful if for a normal window the decoration renders its own
1041 * shadows or round corners and thus needs alpha channel. But in maximized state the decoration
1042 * is fully opaque. By disabling the alpha channel the Compositor can optimize the rendering.
1043 *
1044 * @param enabled If @c true alpha channel is enabled, if @c false alpha channel is disabled
1045 * @see isAlphaEnabled
1046 * @see alphaEnabledChanged
1047 * @since 4.10
1048 **/
1049 void setAlphaEnabled(bool enabled);
1050 /**
1051 * This slot can be reimplemented to return the regions defined
1052 * by KDecorationDefines::Region.
1053 *
1054 * The default implementation always returns an empty region.
1055 *
1056 * @since 4.8
1057 */
1058 QRegion region(KDecorationDefines::Region r);
1059
1060private:
1061 KDecorationBridge* bridge_;
1062 QWidget* w_;
1063 KDecorationFactory* factory_;
1064 friend class KDecorationOptions; // for options_
1065 friend class KDecorationUnstable; // for bridge_
1066 static KDecorationOptions* options_;
1067 KDecorationPrivate* d;
1068
1069};
1070
1071/**
1072 * @warning THIS CLASS IS UNSTABLE!
1073 */
1074class KWIN_EXPORT KDecorationUnstable
1075 : public KDecoration
1076{
1077 Q_OBJECT
1078
1079public:
1080 KDecorationUnstable(KDecorationBridge* bridge, KDecorationFactory* factory);
1081 virtual ~KDecorationUnstable();
1082 /**
1083 * This function can return additional padding values that are added outside the
1084 * borders of the window, and can be used by the decoration if it wants to paint
1085 * outside the frame.
1086 *
1087 * The typical use case is for drawing a drop shadow or glowing effect around the window.
1088 *
1089 * The area outside the frame cannot receive input, and when compositing is disabled,
1090 * painting is clipped to the mask, or the window frame if no mask is defined.
1091 */
1092 virtual void padding(int &left, int &right, int &top, int &bottom) const;
1093 /**
1094 * Returns @a true if compositing--and therefore ARGB--is enabled.
1095 */
1096 bool compositingActive() const;
1097
1098 // Window tabbing
1099
1100 /**
1101 * Returns whether or not this client group contains the active client.
1102 */
1103 bool isInActiveTabGroup();
1104 /**
1105 * Return the amount of tabs in this group
1106 */
1107 int tabCount() const;
1108
1109 /**
1110 * Return the icon for the tab at index \p idx (\p idx must be smaller than tabCount())
1111 */
1112 QIcon icon(int idx) const;
1113
1114 /**
1115 * Return the caption for the tab at index \p idx (\p idx must be smaller than tabCount())
1116 */
1117 QString caption(int idx) const;
1118
1119 /**
1120 * Return the unique id for the tab at index \p idx (\p idx must be smaller than tabCount())
1121 */
1122 long tabId(int idx) const;
1123 /**
1124 * Returns the id of the currently active client in this group.
1125 */
1126 long currentTabId() const;
1127 /**
1128 * Activate tab for the window with the id \p id.
1129 */
1130 void setCurrentTab(long id);
1131
1132 /**
1133 * Entab windw with id \p A beFORE the window with the id \p B.
1134 */
1135 virtual void tab_A_before_B(long A, long B);
1136 /**
1137 * Entab windw with id \p A beHIND the window with the id \p B.
1138 */
1139 virtual void tab_A_behind_B(long A, long B);
1140 /**
1141 * Remove the window with the id \p id from its tabgroup and place it at \p newGeom
1142 */
1143 virtual void untab(long id, const QRect& newGeom);
1144
1145 /**
1146 * Close the client with the id \p id.
1147 */
1148 void closeTab(long id);
1149 /**
1150 * Close all windows in this group.
1151 */
1152 void closeTabGroup();
1153 /**
1154 * Display the right-click client menu belonging to the client at index \p index at the
1155 * global coordinates specified by \p pos.
1156 */
1157 void showWindowMenu(const QPoint& pos, long id);
1158 /**
1159 * unshadow virtuals
1160 */
1161 using KDecoration::caption;
1162 using KDecoration::icon;
1163 using KDecoration::showWindowMenu;
1164 /**
1165 * Determine which action the user has mapped \p button to. Useful for determining whether
1166 * a button press was for window tab dragging or for displaying the client menu.
1167 */
1168 WindowOperation buttonToWindowOperation(Qt::MouseButtons button);
1169};
1170
1171inline
1172KDecorationDefines::MaximizeMode operator^(KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2)
1173{
1174 return KDecorationDefines::MaximizeMode(int(m1) ^ int(m2));
1175}
1176
1177inline
1178KDecorationDefines::MaximizeMode operator&(KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2)
1179{
1180 return KDecorationDefines::MaximizeMode(int(m1) & int(m2));
1181}
1182
1183inline
1184KDecorationDefines::MaximizeMode operator|(KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2)
1185{
1186 return KDecorationDefines::MaximizeMode(int(m1) | int(m2));
1187}
1188
1189inline QWidget* KDecoration::widget()
1190{
1191 return w_;
1192}
1193
1194inline const QWidget* KDecoration::widget() const
1195{
1196 return w_;
1197}
1198
1199inline KDecorationFactory* KDecoration::factory() const
1200{
1201 return factory_;
1202}
1203
1204inline bool KDecoration::isOnAllDesktops() const
1205{
1206 return desktop() == NET::OnAllDesktops;
1207}
1208
1209inline int KDecoration::width() const
1210{
1211 return geometry().width();
1212}
1213
1214inline int KDecoration::height() const
1215{
1216 return geometry().height();
1217}
1218
1219/** @} */
1220
1221Q_DECLARE_OPERATORS_FOR_FLAGS(KDecoration::QuickTileMode)
1222
1223#endif
1224