1 /**
2 * KStyle for KDE4
3 * Copyright (C) 2004-2005 Maksim Orlovich <maksim@kde.org>
4 * Copyright (C) 2005,2006 Sandro Giessl <giessl@kde.org>
5 *
6 * Based in part on the following software:
7 * KStyle for KDE3
8 * Copyright (C) 2001-2002 Karol Szwed <gallium@kde.org>
9 * Portions (C) 1998-2000 TrollTech AS
10 * Keramik for KDE3,
11 * Copyright (C) 2002 Malte Starostik <malte@kde.org>
12 * (C) 2002-2003 Maksim Orlovich <maksim@kde.org>
13 * Portions (C) 2001-2002 Karol Szwed <gallium@kde.org>
14 * (C) 2001-2002 Fredrik Höglund <fredrik@kde.org>
15 * (C) 2000 Daniel M. Duley <mosfet@kde.org>
16 * (C) 2000 Dirk Mueller <mueller@kde.org>
17 * (C) 2001 Martijn Klingens <klingens@kde.org>
18 * (C) 2003 Sandro Giessl <sandro@giessl.com>
19 * This library is free software; you can redistribute it and/or
20 * modify it under the terms of the GNU Library General Public
21 * License as published by the Free Software Foundation; either
22 * version 2 of the License, or (at your option) any later version.
23 *
24 * This library is distributed in the hope that it will be useful,
25 * but WITHOUT ANY WARRANTY; without even the implied warranty of
26 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
27 * Library General Public License for more details.
28 *
29 * You should have received a copy of the GNU Library General Public License
30 * along with this library; see the file COPYING.LIB. If not, write to
31 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
32 * Boston, MA 02110-1301, USA.
33 */
34
35 #ifndef KDE_K4STYLE_H
36 #define KDE_K4STYLE_H
37
38 #include <kdelibs4support_export.h>
39
40 #include <QCommonStyle>
41 #include <QPalette>
42 #include <QStylePlugin>
43 #include <typeinfo>
44
45 class QStyleOptionProgressBar;
46 class QStyleOptionTab;
47
48 class K4StylePrivate;
49 /**
50 * Makes style coding more convenient.
51 *
52 * @todo and allows to style KDE specific widgets.
53 *
54 * K4Style strives to ease style development by implementing various QStyle
55 * methods. These implementations are based on
56 * -# the concept of Layout Properties. These properties can be set using
57 * setWidgetLayoutProp(). K4Style uses this information to respect various
58 * metrics (like space between primitives or margins around widget contents)
59 * or turn specific features on or off.
60 * -# the concept of K4Style Primitives. These can be implemented by overriding
61 * drawKStylePrimitive() and providing drawing methods for specific
62 * primitives. Often, the drawing of more complex widgets consists of
63 * several primitives.
64 *
65 * In the following modules, information about related members is collected:
66 * - \ref OptionGroup
67 * - \ref WidgetGroup
68 *
69 * @author Maksim Orlovich (maksim\@kde.org)
70 * @author Sandro Giessl (giessl\@kde.org)
71 *
72 * @see KStyleFactory for how to implement the style plugin interface.
73 */
74 // TODO: From 'Qt4 Themes' discussion on kde-devel
75 // - Remi Villatel: extend QStyle enums for KColorButton, KColorCombo, KKeyButton, split PE_HeaderSection into KPopupTitle, PopupMenuTitle, TaskContainer)
76 // - RV: KLineEdit "plays with its colors" - related to K4Style?
77 // - RV: KMulitTabBarTab ... does it need support from K4Style (instead of manual button rotation etc.)? Or is it dumped already?
78 // - RV: KTabCtl draws itself mimicking QDrawShadeThingies
79 // - RV: fixed colors (e.g. Konqueror, KToolbarButton label text ->KPE_ToolbarButton?): To prevent hacks like "preventing any PaletteChange()"... mor related to KDE4 color schemes... I guess
80 // - LM: User interface guidelines... related to K4Style?
81 // - e.g. drawFancyPE() in kdeui for KDE widgets: check "qobject_cast<K4Style*>(style())", or fallback drawing...
82 // TODO: implement standardIcon().. and what about standardPalette()?
83 // TODO: maybe the arrow in CE_PushButtonLabel should be painted in CE_PushButtonBevel like QCommonStyle
84
85 class KDELIBS4SUPPORT_DEPRECATED_EXPORT K4Style: public QCommonStyle
86 {
87 Q_OBJECT
88
89 public:
90 K4Style();
91 ~K4Style() override;
92
93 /**
94 * Returns the default widget style.
95 */
96 static QString defaultStyle();
97 /**
98 * Runtime element extension
99 * This is just convenience and does /not/ require the using widgets style to inherit K4Style
100 * (i.e. calling this while using cleanlooks won't segfault or so but just return 0)
101 * Returns a unique id for an element string (e.g. "CE_CapacityBar")
102 *
103 * For simplicity, only StyleHints, ControlElements and their SubElements are supported
104 * If you don't need extended SubElement functionality, just drop it
105 *
106 * @param element The style element, represented as string.
107 * Naming convention: "appname.(2-char-element-type)_element"
108 * where the 2-char-element-type is of {SH, CE, SE}
109 * (widgets in kdelibs don't have to pass the appname)
110 * examples: "CE_CapacityBar", "amarok.CE_Analyzer"
111 * @param widget Your widget ("this") passing this is mandatory, passing NULL will just return 0
112 * @returns a unique id for the @p element string or 0, if the element is not supported by the
113 * widgets current style
114 *
115 * Important notes:
116 * 1) If your string lacks the matching "SH_", "CE_" or "SE_" token the element
117 * request will be ignored (return is 0)
118 * 2) Try to avoid custom elements and use default ones (if possible) to get better style support
119 * and keep UI coherency
120 * 3) If you cache this value (good idea, this requires a map lookup) don't (!) forget to catch
121 * style changes in QWidget::changeEvent()
122 */
123 static StyleHint customStyleHint(const QString &element, const QWidget *widget);
124 static ControlElement customControlElement(const QString &element, const QWidget *widget);
125 static SubElement customSubElement(const QString &element, const QWidget *widget);
126
127 protected:
128
129 /**
130 * Runtime element extension, allows inheriting styles to add support custom elements
131 * merges supporting inherit chains
132 * Supposed to be called e.g. in your constructor.
133 *
134 * NOTICE: in order to have this work, your style must provide
135 * an "X-KDE-CustomElements" classinfo, i.e.
136 * class MyStyle : public K4Style
137 * {
138 * Q_OBJECT
139 * Q_CLASSINFO ("X-KDE-CustomElements", "true")
140 *
141 * public:
142 * .....
143 * }
144 *
145 * @param element The style element, represented as string.
146 * Suggested naming convention: appname.(2-char-element-type)_element
147 * where the 2-char-element-type is of {SH, CE, SE}
148 * widgets in kdelibs don't have to pass the appname
149 * examples: "CE_CapacityBar", "amarok.CE_Analyzer"
150 *
151 * Important notes:
152 * 1) If your string lacks the matching "SH_", "CE_" or "SE_" token the element
153 * request will be ignored (return is 0)
154 * 2) To keep UI coherency, don't support any nonsense in your style, but convince app developers
155 * to use standard elements - if available
156 */
157 StyleHint newStyleHint(const QString &element);
158 ControlElement newControlElement(const QString &element);
159 SubElement newSubElement(const QString &element);
160
161 /** @name Helper Methods
162 * These are methods helping with QRect handling, for example.
163 */
164 //@{
165 /**
166 Draws inside the rectangle using a thinkness 0 pen. This is what drawRect in Qt3 used to do.
167 */
168 void drawInsideRect(QPainter *p, const QRect &r) const;
169
170 /**
171 Returns a w x h QRect center inside the 'in' rectangle
172 */
173 QRect centerRect(const QRect &in, int w, int h) const;
174
175 /**
176 Return a size-dimension QRect centered inside the 'in' rectangle
177 */
178 QRect centerRect(const QRect &in, const QSize &size) const;
179 //@}
180
181 /**
182 * \defgroup OptionGroup K4Style option representation
183 * Things related to the representation of options passed when drawing things.
184 */
185 //@{
186 /**
187 * @brief A representation for colors for use as a widget layout property.
188 *
189 * This marshals to and from integers.
190 */
191 class KDELIBS4SUPPORT_DEPRECATED_EXPORT ColorMode //krazy:exclude=dpointer (lightweight helper)
192 {
193 public:
194 /**
195 K4Style understands two kinds of colors:
196 * -# Palette entries. This means the item must be painted with a specific
197 * color role from the palette.
198 * -# Auto-selected black or white, dependent on the brightness of a certain
199 * color role from the palette.
200 */
201 enum Mode {
202 PaletteEntryMode,
203 BWAutoContrastMode = 0x8000000
204 };
205 private:
206 Mode mode;
207 QPalette::ColorRole role;
208 public:
209
210 /// Constructor, using a the given palette role @p _role
211 /// and a default mode.
212 ColorMode(QPalette::ColorRole _role);
213
214 /// Constructor with explicit color mode and palette roles.
215 ColorMode(Mode _mode, QPalette::ColorRole _role);
216
217 /// Represent as an int to store as a property
218 operator int() const;
219
220 /// Decode from an int.
221 ColorMode(int encoded);
222
223 /// Return the color corresponding to our role from the palette,
224 /// automatically compensating for the contrast mode.
225 QColor color(const QPalette &palette);
226 };
227
228 /**
229 Base for our own option classes.
230 The idea here is that Option is the main base, and all the
231 public bases inherit off it indirectly using OptionBase,
232 which helps implement the default handling
233
234 When implementing the actual types, just implement the default ctor,
235 filling in defaults, and you're set.
236 */
237 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT Option {
~OptionOption238 virtual ~Option() {} //So dynamic_cast works, and g++ shuts up
239 };
240
241 /**
242 Intermediatary base that helps implement subtypes of Option
243 that properly handle defaults
244
245 EventualSubtype --- the type of option which will be implemented
246 by inheritting of this class
247
248 BaseType --- the type of option from which this should inherit
249 */
250 template<typename EventualSubtype, typename BaseType>
251 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT OptionBase: public BaseType {
252 /** Default value for this option. Uses the default constructor
253 of EventualSubtype to create the option.
254 */
defaultOptionOptionBase255 static EventualSubtype *defaultOption()
256 {
257 static EventualSubtype *theDefault = nullptr; //### function static, not very nice,
258 //but avoids need for explicit instantiation.
259
260 if (!theDefault) {
261 theDefault = new EventualSubtype;
262 }
263
264 return theDefault;
265 }
266 };
267
268 /**
269 The extractOption method casts the passed in option object, and returns
270 it, if available, or the defaults for the given type. When implementing
271 drawing of things with associated options, just use this to extract
272 the parameter.
273 */
274 template<typename T>
275 static T extractOption(Option *option);
276
277 /**
278 Option representing the color of the thing to draw. Used for arrows, and for text
279 (the latter actually uses TextOption)
280 */
281 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT ColorOption: public OptionBase<ColorOption, Option> {
282 /** Color to use for the drawing. Public, modifiable. */
283 ColorMode color;
284
ColorOptionColorOption285 ColorOption(): color(QPalette::ButtonText)
286 {}
287 };
288
289 /**
290 Option for drawing icons: represents whether the icon should be active or not.
291 The implementation is responsible for all other flags
292 */
293 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT IconOption: public OptionBase<IconOption, Option> {
294 bool active; ///< Is the icon active?
295 QIcon icon; ///< Icon drawn by this option
296 QSize size;
297
IconOptionIconOption298 IconOption(): active(false)
299 {}
300 };
301
302 /**
303 * Option for drawing double scrollbar buttons, indicating whether
304 * a button should be drawn active or not.
305 * @sa ScrollBar::Primitive
306 */
307 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT DoubleButtonOption: public OptionBase<DoubleButtonOption, Option> {
308 /**
309 * List of active button possibilities.
310 */
311 enum ActiveButton {
312 None, ///< No button is active
313 Top, ///< Vertical scrollbar: The upper button is active
314 Left, ///< Horizontal scrollbar: The left button is active
315 Right, ///< Horizontal scrollbar: The right button is active
316 Bottom ///< Vertical scrollbar: The lower button is active
317 };
318
319 /**
320 Whether any of the two buttons is active; and if yes, which
321 one.
322 */
323 ActiveButton activeButton;
324
DoubleButtonOptionDoubleButtonOption325 DoubleButtonOption(): activeButton(None)
326 {}
327
328 /**
329 * Convenience constructor.
330 *
331 * @param ab initializes the active button property
332 */
DoubleButtonOptionDoubleButtonOption333 DoubleButtonOption(ActiveButton ab): activeButton(ab)
334 {}
335 };
336
337 /**
338 * Option for drawing WT_Window titlebar buttons, indicating whether
339 * the button is pressed, and containing the window icon
340 * @sa Window
341 */
342 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT TitleButtonOption: public OptionBase<TitleButtonOption, Option> {
343 bool active; ///< whether the button is pressed
344 QIcon icon; ///< window Icon
345 // /// whether the button is hovered, this doesn't work at the moment (not even in any Qt style)...
346 // bool hover;
347
TitleButtonOptionTitleButtonOption348 TitleButtonOption(): active(false)/*, hover(false)*/
349 {}
350
351 /**
352 * Convenience constructor.
353 *
354 * @param act initializes the active button property
355 */
TitleButtonOptionTitleButtonOption356 TitleButtonOption(bool act): active(act)
357 {}
358 };
359
360 ///Option representing text drawing info. For Generic::Text.
361 struct KDELIBS4SUPPORT_DEPRECATED_EXPORT TextOption: public OptionBase<TextOption, ColorOption> {
362 Qt::Alignment hAlign; ///< The horizontal alignment, default is Qt::AlignLeft
363 QString text; ///< The text to draw
364
365 TextOption();
366
367 /**
368 * Convenience constructor.
369 *
370 * @param _text initializes the text string property
371 */
372 TextOption(const QString &_text);
373
374 /**
375 * Called by the constructor to set the default value of @c hAlign
376 */
377 void init();
378 };
379 //@}
380
381 /**
382 * \defgroup WidgetGroup K4Style widget representation
383 * Things related to the representation of widgets.
384 */
385 //@{
386 /**
387 This enum is used to represent K4Style's concept of
388 a widget, and to associate drawing requests and metrics
389 with it. The generic value is used for primitives and metrics
390 that are common between many widgets
391 */
392 enum WidgetType {
393 WT_Generic, ///< @sa Generic
394 WT_PushButton, ///< @sa PushButton
395 WT_Splitter, ///< @sa Splitter
396 WT_CheckBox, ///< @sa CheckBox
397 WT_RadioButton, ///< @sa RadioButton
398 WT_DockWidget, ///< @sa DockWidget
399 WT_ProgressBar, ///< @sa ProgressBar
400 WT_MenuBar, ///< @sa MenuBar
401 WT_MenuBarItem, ///< @sa MenuBarItem
402 WT_Menu, ///< @sa Menu
403 WT_MenuItem, ///< @sa MenuItem
404 WT_ScrollBar, ///< @sa ScrollBar
405 WT_TabBar, ///< @sa TabBar
406 WT_TabWidget, ///< @sa TabWidget
407 WT_Slider, ///< @sa Slider
408 WT_Tree, ///< @sa Tree
409 WT_SpinBox, ///< @sa SpinBox
410 WT_ComboBox, ///< @sa ComboBox
411 WT_Header, ///< @sa Header
412 WT_LineEdit, ///< @sa LineEdit
413 WT_GroupBox, ///< @sa GroupBox
414 WT_StatusBar, ///< @sa StatusBar
415 WT_ToolBar, ///< @sa ToolBar
416 WT_ToolButton, ///< @sa ToolButton
417 WT_ToolBoxTab, ///< @sa ToolBoxTab
418 WT_Window, ///< @sa Window
419 WT_Limit = 0xFFFF ///< For enum extensibility
420 };
421
422 /**
423 These constants describe how to access various fields of a margin property.
424 For example, to set an additional top margin of 2 pixels, use
425 * \code
426 * setWidgetLayoutProp(WT_SomeWidget, SomeWidget::Margin + Top, 2);
427 * \endcode
428 */
429 enum MarginOffsets {
430 MainMargin, /**< The main margin is applied equally on each side.
431 * In the example above, 'SomeWidget::Margin+MainMargin' is
432 * the same as 'SomeWidget::Margin'. */
433 Top, ///< Apply an additional top margin.
434 Bot, ///< Apply an additional bottom margin.
435 Left, ///< Apply an additional left margin.
436 Right, ///< Apply an additional right margin.
437 MarginInc /**< Used to reserve space in an enum for the Top, Bot,
438 * Left, Right margins. */
439 };
440
441 /**
442 * Basic primitive drawing operations. Are intended to be used in every
443 * WidgetType combination.
444 */
445 struct Generic {
446 /**
447 * Layout properties. These can be set with setWidgetLayoutProp()
448 * Generic LayoutProps contain a few properties which are not
449 * directly related to a specific widget type.
450 */
451 enum LayoutProp {
452 DefaultFrameWidth, ///< The FrameWidth used by LineEdit, etc..., default is \b 2 [sets QStyle::PM_DefaultFrameWidth]
453 DefaultLayoutSpacing, ///< The spacing used by layouts, unless the style implements layoutSpacingImplementation(), default is \b 6 [sets QStyle::PM_DefaultLayoutSpacing]
454 DefaultLayoutMargin ///< The margin used by layouts, default is \b 9 [sets QStyle::PM_DefaultChildMargin and QStyle::PM_DefaultTopLevelMargin]
455 };
456
457 /**
458 * Primitive drawing operations.
459 * @note The arrows are centering primitives, which means they draw in
460 * the center of the specified rectangle.
461 */
462 enum Primitive {
463 Text = 0xFFFF, ///< Passes in TextOption
464 Icon, ///< Passes in IconOption
465 FocusIndicator, ///< Indication that this widget has focus
466 Frame, /**< Frame around widget
467 * @note QFrame derived widgets are painted using
468 * WT_Generic widget type and this Generic::Frame primitive. */
469 ArrowUp, ///< Up arrow (pointing up)
470 ArrowDown, ///< Down arrow
471 ArrowRight, ///< Right arrow
472 ArrowLeft ///< Left arrow
473 };
474 };
475
476 /**
477 * @brief Describes widgets like QPushButton.
478 *
479 * @sa WT_PushButton
480 */
481 struct PushButton {
482 /**
483 * The layout of a PushButton is structured as follows:
484 * -# Between the very outside and the bevel is the default indicator
485 * area, controlled by the @c PushButton::DefaultIndicatorMargin .
486 * -# From the bevel, the content and focus rect margins are measured.
487 * Only the content margin is used to size the content area.
488 * -# Inside the content area, @c PushButton::MenuIndicatorSize is allocated to the down
489 * arrow if there is a popup menu.
490 * -# @c PushButton::TextToIconSpace is allocated between icon and text if both exist
491 *
492 * @sa setWidgetLayoutProp()
493 */
494 enum LayoutProp {
495 ContentsMargin, ///< (\b 5) space between the bevel and the button contents
496 FocusMargin = ContentsMargin + MarginInc, ///< (\b 3) Used to calculate the area of the focus indicator. Measured from the bevel.
497 DefaultIndicatorMargin = FocusMargin + MarginInc, ///< (\b 0 ?) Default indicator between the very outside and the bevel. KStyle may reserve this for auto-default buttons, too, for consistency's sake. [the MainMargin sets QStyle::PM_ButtonDefaultIndicator]
498 PressedShiftHorizontal = DefaultIndicatorMargin + MarginInc, ///< (\b 2) horizontal contents shift for pressed buttons [sets QStyle::PM_ButtonShiftHorizontal]
499 PressedShiftVertical, ///< (\b 2) vertical contents shift for pressed buttons [sets QStyle::PM_ButtonShiftVertical]
500 MenuIndicatorSize, ///< (\b 8) Space inside the content area, which is allocated to the down arrow if there is a popup menu [sets QStyle::PM_MenuButtonIndicator, except for toolbuttons]
501 TextToIconSpace ///< (\b 6) space between the icon and the text if both exist
502 };
503
504 /**
505 * Relevant Generic elements:
506 * - @c Generic::Text the button's text
507 * - @c Generic::FocusIndicator indicating that the button has keyboard focus
508 * - @c Generic::ArrowDown indicating that the button has a popup menu associated to it
509 *
510 * [K4Style implements @c QStyle::CE_PushButtonBevel to compose the primitives]
511 *
512 * @sa drawKStylePrimitive()
513 */
514 enum Primitive {
515 Panel, /**< the pushbutton panel
516 * [implements QStyle::PE_PanelButtonCommand] */
517 DefaultButtonFrame /**< frame indicating a default button, painted before
518 * the button Panel
519 * [implements QStyle::PE_FrameDefaultButton] */
520 };
521 };
522
523 /**
524 * @brief Describes widgets like QSplitter.
525 *
526 * @sa WT_Splitter
527 */
528 struct Splitter {
529 /**
530 * @sa setWidgetLayoutProp()
531 */
532 enum LayoutProp {
533 Width ///< (\b 6) size of the splitter handle [sets QStyle::PM_SplitterWidth]
534 };
535
536 /**
537 * [the Handles implement QStyle::CE_Splitter]
538 *
539 * @sa drawKStylePrimitive()
540 */
541 enum Primitive {
542 HandleHor, /**< The splitter handle, horizontal. Flags: @c State_Enabled&&State_MouseOver for mouseOver */
543 HandleVert /**< The splitter handle, vertical. Flags: @c State_Enabled&&State_MouseOver for mouseOver */
544 };
545 };
546
547 /**
548 * @brief Describes widgets like QCheckBox.
549 *
550 * @sa WT_CheckBox
551 */
552 struct CheckBox {
553 /**
554 * @sa setWidgetLayoutProp()
555 */
556 enum LayoutProp {
557 Size, ///< (\b 16) size of the checkbox [sets PM_IndicatorWidth, PM_IndicatorHeight]
558 BoxTextSpace, ///< (\b 6) space to leave between checkbox and text (and icon between them in case there is one)
559 NoLabelFocusMargin, /**< (\b 1) rectangle to apply to the checkbox rectangle
560 * to get where to paint the focus rectangle in
561 * case of a labelless checkbox */
562 FocusMargin = NoLabelFocusMargin + MarginInc ///< (\b 0) margin around the checkbox contents reserved for the focus rect @todo have a look, it isn't as nice as plastique etc.
563 };
564
565 /**
566 * Relevant elements:
567 * - @c Generic::Text the CheckBox label alongside the CheckBox
568 * - @c Generic::FocusIndicator the focus indicator. Usually drawn around the
569 * text label. If no label exists, it is drawn around the CheckBox.
570 *
571 * [check primitives implement QStyle::PE_IndicatorCheckBox]
572 * [K4Style implements QStyle::CE_CheckBox to compose a CheckBox using
573 * the mentioned primitives]
574 *
575 * @sa drawKStylePrimitive()
576 */
577 enum Primitive {
578 CheckOn, ///< checkbox which is checked
579 CheckOff, ///< checkbox which is not checked
580 CheckTriState ///< tristate checkbox (neither off nor on)
581 };
582 };
583
584 /**
585 * @brief Describes widgets like QRadioButton.
586 */
587 struct RadioButton {
588 /**
589 * @sa setWidgetLayoutProp()
590 */
591 enum LayoutProp {
592 Size, /**< [sets QStyle::PM_ExclusiveIndicatorWidth,
593 * QStyle::PM_ExclusiveIndicatorHeight]
594 * @sa CheckBox::Size */
595 BoxTextSpace, ///< @sa CheckBox::BoxTextSpace
596 FocusMargin ///< @sa CheckBox::FocusMargin
597 };
598
599 /**
600 * Relevant Generic elements:
601 * - @c Generic::Text the RadioButton label alongside the RadioButton
602 * - @c Generic::FocusIndicator the keyboard focus indicator
603 *
604 * [check primitives implement QStyle::PE_IndicatorRadioButton]
605 * [K4Style implements QStyle::CE_RadioButton to compose a RadioButton using
606 * the mentioned primitives]
607 *
608 * @sa drawKStylePrimitive()
609 */
610 enum Primitive {
611 RadioOn, ///< radiobutton which is checked
612 RadioOff ///< radiobutton which is not checked
613 };
614 };
615
616 /**
617 * @brief Describes the title of a dock widget.
618 *
619 * @sa WT_DockWidget
620 */
621 struct DockWidget {
622 /**
623 * @sa setWidgetLayoutProp()
624 */
625 enum LayoutProp {
626 TitleTextColor, ///< (\b ColorMode(QPalette::HighlightedText)) color mode of the title text
627 TitleMargin, ///< (\b 2) Margin around title contents: Note that the symmetric margin (MainMargin) is used to size the title! Additional the Left and Right margins can be used to position the title text a little, though (to set Top and Bottom is not advisable). [the MainMargin sets QStyle::PM_DockWidgetTitleMargin]
628 FrameWidth = TitleMargin + MarginInc, ///< (\b 3) width of the frame around floating dockwidgets [sets QStyle::PM_DockWidgetFrameWidth]
629 SeparatorExtent ///< (\b 6) width of the area which separates the (docked) dock window from the window contents [sets QStyle::PM_DockWidgetSeparatorExtent]
630 };
631
632 /**
633 * Relevant Generic elements:
634 * - @c Generic::Text the title text
635 * - @c Generic::Frame the frame around floating dockwidgets
636 *
637 * [K4Style implements @c QStyle::CE_DockWidgetTitle to split it into K4Style primitives]
638 *
639 * @sa drawKStylePrimitive()
640 */
641 enum Primitive {
642 TitlePanel, ///< the panel/background of the title bar
643 SeparatorHandle ///< the splitter between dockwidgets
644 };
645 };
646
647 /**
648 * @brief Describes widgets like QProgressBar.
649 *
650 * @todo support for Qt > 4.1 orientation, bottomToTop, invertedAppearance properties!
651 *
652 * @sa WT_ProgressBar
653 */
654 struct ProgressBar {
655 /**
656 * @sa setWidgetLayoutProp()
657 */
658 enum LayoutProp {
659 GrooveMargin, ///< (\b 2) Margin to allocate for the groove. Content area will be inside of it.
660 SideText = GrooveMargin + MarginInc, ///< (\b false) set this to true to have the text positionned to the side
661 SideTextSpace, ///< (\b 3) Extra space besides that needed for text to allocate to side indicator (on both sides).
662 Precision, ///< (\b 1) The indicator size will always be a multiple of this (modulo busy indicator size clamping). [sets QStyle::PM_ProgressBarChunkWidth]
663 BusyIndicatorSize, ///< (\b 10) The busy indicator size, in percent of area size.
664 MaxBusyIndicatorSize ///< (\b 10000) size limit on the busy indicator size
665 };
666
667 /**
668 * Relevant Generic elements:
669 * - @c Generic::Text the progress label
670 *
671 * @sa drawKStylePrimitive()
672 */
673 enum Primitive {
674 Groove, /**< the progressbar groove, drawn before the progress
675 * Indicator [implements QStyle::CE_ProgressBarGroove] */
676 Indicator, ///< The actual bar indicating the progress...
677 BusyIndicator /**< Used to indicate business, for example when
678 * no progress is known (minimum and maximum values
679 * both set to 0) */
680 };
681 };
682
683 /**
684 * @brief Describes widgets like QMenuBar.
685 *
686 * @sa WT_MenuBar
687 */
688 struct MenuBar {
689 /**
690 * @sa setWidgetLayoutProp()
691 */
692 enum LayoutProp {
693 Margin, /**< (MainMargin \b 2, Left \b 4, Right \b 4)
694 * Margin rectangle for the contents. */
695 ItemSpacing = Margin + MarginInc ///< (\b 14) Space between items [sets QStyle::PM_MenuBarItemSpacing]
696 };
697
698 /**
699 * @sa drawKStylePrimitive()
700 */
701 enum Property {
702 EmptyArea /**< Empty area of a menu bar, e.g. background
703 * color. Maybe the place to fake toolbar separators (?)
704 * [implements QStyle::CE_MenuBarEmptyArea] */
705 };
706 };
707
708 /**
709 * @brief Describes MenuBar items.
710 *
711 * Relevant elements:
712 * - @c Generic::Text text appearing as menubar entry
713 */
714 struct MenuBarItem {
715 /**
716 * @sa setWidgetLayoutProp()
717 */
718 enum LayoutProp {
719 Margin, /**< (\b 1) Margin rectangle to allocate for any
720 * bevel, etc. (Text will be drawn with
721 * the inside rect). */
722 Dummy = Margin + MarginInc //Paranoia about underlying type
723 };
724
725 /**
726 * @sa drawKStylePrimitive()
727 */
728 enum Primitive {
729 Panel ///< The panel/background of a menubar item. Interesting flags: State_Selected && State_HasFocus for mouseOver, State_Sunken for pressed state.
730 };
731 };
732
733 /**
734 * @brief Describes a menu.
735 *
736 * @sa WT_Menu
737 */
738 struct Menu {
739 /**
740 * @sa setWidgetLayoutProp()
741 */
742 enum LayoutProp {
743 FrameWidth, ///< (\b 1) The width of the frame, note that this does not affect the layout.
744 Margin, ///< (\b 3) The margin of the menu. @todo have a look at comments at PM_MenuHMargin...
745 ScrollerHeight = Margin + MarginInc, ///< (\b 10) Height of a menu scroller. [sets QStyle::PM_MenuScrollerHeight]
746 TearOffHeight ///< (\b 10) Height of the TearOff area. [sets QStyle::PM_MenuTearoffHeight]
747 };
748
749 /**
750 * Relevant Generic elements:
751 * - @c Generic::Frame frame around the menu panel
752 *
753 * @sa drawKStylePrimitive()
754 */
755 enum Primitive {
756 Background, ///< Menu and MenuItem background
757 TearOff, /**< paints the area where a menu can be teared off
758 * [implements QStyle::CE_MenuTearoff] */
759 Scroller /**< scrolling areas in a QMenu
760 * [implements QStyle::CE_MenuScroller] */
761 };
762 };
763
764 /**
765 * @brief Describes an item in a menu.
766 *
767 * MenuItems are layouted like this:
768 * -# There are two MenuItem modes, toggled by @c LP_MenuItem_CheckAlongsideIcon.
769 * Horizontal layout inside the items is as follow:
770 * - @c LP_MenuItem_CheckAlongsideIcon disabled:
771 * |icon/checkmark|IconSpace|text|AccelSpace|accel|ArrowSpace|ArrowWidth|
772 * - @c LP_MenuItem_CheckAlongsideIcon enabled:
773 * |checkmark|CheckSpace|icon|IconSpace|text|AccelSpace|accel|ArrowSpace|ArrowWidth|
774 * -# The icon/checkmark column is at least @c LP_MenuItem_CheckWidth wide in all cases.
775 * -# Then Margin is applied outside that.
776 *
777 * @note For the subprimitives the passed rect is their own.
778 * @note Background is erased with WT_Menu/Menu::Background.
779 *
780 * @sa WT_MenuItem
781 */
782 struct MenuItem {
783 /**
784 * @sa setWidgetLayoutProp()
785 */
786 enum LayoutProp {
787 Margin, ///< (\b 2) margin for each entry
788 CheckAlongsideIcon = Margin + MarginInc,
789 /**< (\b 0) Set to non-zero to have checkmarks painted
790 * separate from icons. */
791 CheckWidth, /**< (\b 12) size of the checkmark column
792 * (CheckAlongsideButton enabled). */
793 CheckSpace, /**< (\b 3) Space between the checkmark column and the icon
794 * column (CheckAlongsideButton enabled).*/
795 IconWidth, ///< (\b 12) minimum size of the icon column
796 IconSpace, ///< (\b 3) space between the icon column and text column
797 AccelSpace, ///< (\b 0 ?) space between text and keyboard accelerator label
798 ArrowSpace, ///< (\b 3) space between the text column and arrow column (indicating sub menus)
799 ArrowWidth, ///< (\b 11) space to reserve for the menu arrow column
800 SeparatorHeight,///< (\b 0) heigh of separator
801 MinHeight, ///< (\b 16) limit on the size of item content
802 ActiveTextColor,///< (\b ColorMode(QPalette::HighlightedText)) color for active text and arrow
803 TextColor, ///< (\b ColorMode(QPalette::Text)) color for inactive text and arrow
804 DisabledTextColor, ///< (\b ColorMode(QPalette::Text)) color for inactive + disabled text and arrow
805 ActiveDisabledTextColor ///< (\b ColorMode(QPalette::Text)) color for active + disabled text and arrow
806 };
807
808 /**
809 * Relevant Generic elements:
810 * - @c Generic::Text the text of the menu item
811 * - @c Generic::ArrowLeft @c Generic::ArrowRight arrows indicating a sub-menu
812 *
813 * @sa drawKStylePrimitive()
814 */
815 enum Primitive {
816 CheckColumn, ///< Background of the checkmark/icon column
817 CheckOn, ///< The checkmark - checked
818 CheckOff, ///< The checkmark - not checked
819 RadioOn, ///< The checkmark of exclusive actions - selected
820 RadioOff, ///< The checkmark of exclusive actions - not selected
821 CheckIcon, ///< When @c CheckAlongsideIcon is disabled and item is checked: checkmark Indicator painted below the icon
822 Separator, //A separator item.
823 ItemIndicator //Shows the active item
824 };
825 };
826
827 /**
828 * @brief Describes widgets like QScrollBar.
829 *
830 * @sa WT_ScrollBar
831 */
832 struct ScrollBar {
833 /**
834 * @note Dimensions of LayoutProperties are generally specified with respect
835 * to the vertical scrollbar. Of course, for horizontal ones they're flipped.
836 *
837 * @sa setWidgetLayoutProp()
838 */
839 enum LayoutProp {
840 DoubleTopButton, ///< (\b 0) set to non-zero to have two buttons on top
841 DoubleBotButton, ///< (\b 1) set to non-zero to have two buttons on bottom
842 SingleButtonHeight, ///< (\b 16) height of a single button
843 DoubleButtonHeight, ///< (\b 32) height of a double button
844 BarWidth, ///< (\b 16) width of a scrollbar [sets QStyle::PM_ScrollBarExtent]
845 MinimumSliderHeight,/**< (\b 0 ?) the minimum slider height
846 * @note If the scrollbar is too small to accommodate
847 * this, this will not be enforced. */
848 ArrowColor, /**< (\b ColorMode(ColorMode::BWAutoContrastMode, QPalette::Button)) color mode of a button arrow
849 * @sa ColorMode */
850 ActiveArrowColor /**< (\b ColorMode(ColorMode::BWAutoContrastMode, QPalette::ButtonText)) color mode of a pressed button arrow (?) */
851 };
852
853 /**
854 * Relevant Generic elements:
855 * - The @c Generic arrows
856 *
857 * [Groove Areas implement QStyle::CE_ScrollBarAddPage and QStyle::CE_ScrollBarSubPage]
858 * [Sliders implement QStyle::CE_ScrollBarSlider]
859 *
860 * @sa drawKStylePrimitive()
861 */
862 enum Primitive {
863 SingleButtonVert, ///< used to draw a 1-button bevel, vertical
864 SingleButtonHor, ///< used to draw a 1-button bevel, horizontal
865 DoubleButtonVert, /**< Used to draw a 2-button bevel, vertical.
866 * A DoubleButtonOption is passed to say which
867 * button is pressed. */
868 DoubleButtonHor, /** @see DoubleButtonVert */
869 GrooveAreaVertBottom, ///< scrollbar groove area, vertical. An interesting flag is @c State_Sunken for pressed state
870 GrooveAreaHorRight, ///< scrollbar groove area, horizontal. Flags: @c State_Sunken for pressed state
871 GrooveAreaVertTop, ///< scrollbar groove area, vertical. An interesting flag is @c State_Sunken for pressed state
872 GrooveAreaHorLeft, ///< scrollbar groove area, horizontal. Flags: @c State_Sunken for pressed state
873 SliderVert, ///< scrollbar slider, vertical. Flags: @c State_On&&State_Sunken for pressed state
874 SliderHor ///< scrollbar slider, horizontal. Flags: @c State_On&&State_Sunken for pressed state
875 };
876 };
877
878 /**
879 * @brief Describes a tab bar.
880 *
881 * @sa WT_TabBar
882 */
883 struct TabBar {
884 /**
885 * Each tab is basically built hiearchically out of the following areas:
886 * -# Content area, one of the following layouts:
887 * - Icon <- TextToIconSpace -> Text
888 * - Icon
889 * - Text
890 * -# Bevel: @c LP_TabBar_TabContentsMargin outside of the content area
891 * -# Focus indicator is placed @c LP_TabBar_TabFocusMargin inside the bevel
892 *
893 * @note The side tabs just have those rotated, bottom tabs have the margins reversed.
894 *
895 * @sa setWidgetLayoutProp()
896 */
897 enum LayoutProp {
898 TabContentsMargin, ///< (\b 6) margin around the tab contents, used to size the tab
899 TabFocusMargin = TabContentsMargin + MarginInc,
900 /**< (\b 3) where the tab focus rect is placed, measured from the
901 * tab sides (?) */
902 TabTextToIconSpace = TabFocusMargin + MarginInc,
903 /**< (\b 0 ?) space between icon and text if the tab contains both */
904 TabOverlap, /**< (\b 0) Amount of pixels tabs should overlap. The
905 * paint rectangle will be extended to the left for
906 * all tabs which are not at the beginning (accordingly
907 * extended to the right in RightToLeft mode; extended
908 * to the top for East/West tabs). */
909 BaseHeight, ///< (\b 2) the height of the tabBar's base, usually the frame width [sets QStyle::PM_TabBarBaseHeight] @todo is this used for things like I intended TabWidget::ContentsMargin for?
910 BaseOverlap, ///< (\b 2) the number of pixels the tabs overlap with the base (i.e. tabWidget frame) [sets QStyle::PM_TabBarBaseOverlap]
911 ScrollButtonWidth ///< (\b 10) buttons which are shown when there's not enough space for tabs (A ToolButton is used for this) [sets QStyle::PM_TabBarScrollButtonWidth]
912 };
913
914 /**
915 * Relevant elements:
916 * - @c Generic::Text for the TabBar labels
917 * - @c Generic::FocusIndicator for focused tabs
918 * - @c Generic::Icon for icons associated to tabs
919 * - @c ToolButton::Panel paints the scroll button (when the tabs don't fit the tab bar)
920 */
921 enum Primitive {
922 EastText, /**< Special rotated text for east tabs. */
923 WestText, ///< @see EastText
924 NorthTab, ///< @todo say something about triangular shape etc.
925 EastTab,
926 WestTab,
927 SouthTab,
928 BaseFrame, ///< [implements QStyle::PE_FrameTabBarBase]
929 IndicatorTear /**< painted in the left edge of a tabbar when the left
930 * tab is scrolled out
931 * [implements PE_IndicatorTabTear]
932 * @todo K4Style default implementation...? */
933 };
934 };
935
936 /**
937 * @brief Describes a tab widget (frame).
938 *
939 * Relevant elements:
940 * - @c Generic::Frame for the frame/panel of the TabWidget
941 *
942 * @sa WT_TabWidget
943 */
944 struct TabWidget {
945 /**
946 * @sa setWidgetLayoutProp()
947 */
948 enum LayoutProp {
949 ContentsMargin, /**< (\b 2) Width of the frame around a tab widget.
950 * Margins for a tabwidget with tab position 'North' are
951 * specified as expected. For other positions, the
952 * sides are rotated accordingly, e.g. the left margin
953 * of a 'West' tabwidget is the same as top for a 'North'
954 * tabwidget.
955 * [sets QStyle::SE_TabWidgetTabContents] */
956 DummyProp = ContentsMargin + MarginInc
957 };
958 };
959
960 /**
961 * @brief Describes a slider, like QSlider.
962 *
963 * @sa WT_Slider
964 */
965 struct Slider {
966
967 /**
968 * @note The description applies to horizontal sliders.
969 *
970 * @sa setWidgetLayoutProp()
971 */
972 enum LayoutProp {
973 HandleThickness, ///< (\b 20) The height of a slider handle
974 HandleLength ///< (\b 16) The width of a slider handle [sets QStyle::PM_SliderLength]
975 };
976
977 /**
978 * Relevant Generic elements:
979 * - @c Generic::FocusIndicator indicating keyboard focus
980 *
981 * @sa drawKStylePrimitive()
982 */
983 enum Primitive {
984 HandleVert, ///< A vertical slider handle
985 HandleHor, ///< A horizontal slider handle
986 GrooveVert, ///< A vertical slider groove
987 GrooveHor ///< A horizontal slider groove
988 };
989 };
990
991 /**
992 * @brief Describes an expandable tree, e.g. in a QListView.
993 */
994 struct Tree {
995 /**
996 * For trees, all the control we provide here is to provide a cap on the size
997 * of the expander widget, which is always square. There are 4 primitives to
998 * implement: open and closed expander, and horizontal and vertical lines.
999 * If you're using dots, it's suggested you use global brush alignment to
1000 * keep it all nicely aligned.
1001 *
1002 * @sa setWidgetLayoutProp()
1003 */
1004 enum LayoutProp {
1005 MaxExpanderSize /**< (\b 9) @note If you set MaxExpanderSize to a value less
1006 * than 9, designer will look funny. The value should also
1007 * be odd, or value - 1 will be used.
1008 */
1009 };
1010
1011 /**
1012 * @sa drawKStylePrimitive()
1013 */
1014 enum Primitive {
1015 ExpanderClosed, ///< A closed tree expander, usually drawn as '+'. K4Style has a default implementation (Windows-like look).
1016 ExpanderOpen, ///< An opened tree expander, usually drawn as '-' K4Style has a default implementation.
1017 HorizontalBranch, /**< A horizontal tree line.
1018 * @note If you're using dots, it's suggested you
1019 * use global brush alignment to keep it all nicely
1020 * aligned. */
1021 VerticalBranch /**< @see HorizontalBranch */
1022 };
1023 };
1024
1025 /**
1026 * @brief Describes a widget like QSpinBox.
1027 */
1028 struct SpinBox {
1029 /**
1030 * @note The description applies to LTR (left to right) mode.
1031 *
1032 * -# @c FrameWidth and @c ButtonWidth are used to size
1033 * the contents area. To the EditField, @c FrameWidth
1034 * is added at the left, top, bottom while @c ButtonWidth is added
1035 * at the right.
1036 * -# The @c ButtonMargin is measured from the right side of the
1037 * EditField and the outside. Inside it, the up and down buttons are aligned with
1038 * spacing @c ButtonSpacing.
1039 * -# To make sure that both buttons are always of the same height, enable
1040 * @c SymmetricButtons.
1041 *
1042 * @sa setWidgetLayoutProp()
1043 */
1044 enum LayoutProp {
1045 FrameWidth, /**< (\b 1) Space reserved left, top, bottom of the SpinBox
1046 * [sets QStyle::PM_SpinBoxFrameWidth] */
1047 ButtonWidth, ///< (\b 16) Space reserved for the widget, right of the EditField
1048 ButtonMargin, /**< (MainMargin \b 0, Right Top Bot \b 1)
1049 * Where the up/down buttons are located, measured
1050 * from right of the edit field and the top/right/bottom
1051 * widget edges. */
1052 ButtonSpacing = ButtonMargin + MarginInc, ///< (\b 1) spacing between up/down buttons
1053 SymmetricButtons, /**< (\b 0) Set to non-zero to make sure both buttons are
1054 * always of the same height. To achieve this, the
1055 * spacing of the buttons will be reduced by 1 if
1056 * necessary to avoid rounding problems. Needs to be
1057 * handled in your drawing code. */
1058 SupportFrameless, /**< (\b 0) Set to non-zero to indicate that you are able to
1059 * handle frame-less SpinBoxes. For a SpinBox with no
1060 * frame, FrameWidth and Top/Bottom/Right ButtonMargin
1061 * is ignored. */
1062 ContentsMargin
1063 /**< (\b 5) space between the bevel and the spinbox contents
1064 */
1065 };
1066
1067 /**
1068 * Relevant Generic elements:
1069 * - @c Generic::Frame for the area around text input field and buttons
1070 * - @c Generic::ArrowUp @c Generic::ArrowDown drawn on the buttons
1071 */
1072 enum Primitive {
1073 EditField, /**< the text contents area, painted after Generic::Frame
1074 * @note This is respected only if the combobox is not
1075 * editable. */
1076 UpButton, /**< Panel of the spinbox button which increases the value */
1077 DownButton, /**< Panel of the spinbox button which decreases the value */
1078 ButtonArea, /**< Can be used in addition or instead of
1079 * @c KPE_SpinBox_UpButton and @c KPE_SpinBox_DownButton.
1080 * The button area is painted before them. */
1081 PlusSymbol, /**< Plus symbol painted on top of the up button,
1082 * centering primitive */
1083 MinusSymbol /**< Minus symbol painted on top of the down button,
1084 * centering primitive */
1085 };
1086 };
1087
1088 /**
1089 * @brief Describes a widget like QComboBox.
1090 */
1091 struct ComboBox {
1092 /**
1093 * @note The description applies to LTR (left to right) mode.
1094 *
1095 * -# @c FrameWidth and @c ButtonWidth are used to size
1096 * the contents area. To the EditField, @c FrameWidth
1097 * is added at the left, top, bottom while @c ButtonWidth is added
1098 * at the right.
1099 * -# The @c ButtonMargin is measured from the right side of the
1100 * EditField and the outside. Inside it, the button is aligned.
1101 * -# The @c FocusMargin is measured from the EditField rect.
1102 */
1103 enum LayoutProp {
1104 FrameWidth, /**< (\b 1) @see SpinBox::FrameWidth */
1105 ButtonWidth, /**< (\b 16) @see SpinBox::ButtonWidth */
1106 ButtonMargin, /**< (MainMargin \b 0, Right Top Bot \b 1)
1107 * @see SpinBox::ButtonMargin */
1108 FocusMargin = ButtonMargin + MarginInc,
1109 /**< (\b 1) Focus margin for ComboBoxes that aren't
1110 * editable, measured from the EditField rect */
1111 SupportFrameless = FocusMargin + MarginInc,
1112 /**< (\b 0) @see LP_SpinBox_SupportFrameless same description
1113 * applies here */
1114 ContentsMargin
1115 /**< (\b 5) space between the bevel and the combobox contents
1116 */
1117 };
1118
1119 /**
1120 * Relevant Generic elements:
1121 * - @c Generic::Frame for the area around text input field and button
1122 * - @c Generic::ArrowDown drawn on the button
1123 * - @c Generic::FocusIndicator to indicate keyboard focus
1124 *
1125 * @sa drawKStylePrimitive()
1126 */
1127 enum Primitive {
1128 EditField, /**< @see SpinBox::EditField */
1129 Button /**< The button panel of the combobox */
1130 };
1131 };
1132
1133 /**
1134 * @brief Describes a list header, like in QListView.
1135 *
1136 * @sa WT_Header
1137 */
1138 struct Header {
1139 /**
1140 * @sa setWidgetLayoutProp()
1141 */
1142 enum LayoutProp {
1143 ContentsMargin, /**< (\b 3) margin around contents used to size the header. */
1144 TextToIconSpace = ContentsMargin + MarginInc,
1145 /**< (\b 3) space that is allocated between icon and text
1146 * if both exist
1147 * [sets QStyle::PM_HeaderMargin] */
1148 MarkSize /**< (\b 9) size of the sort indicator in a header
1149 * [sets QStyle::PM_HeaderMarkSize] */
1150 };
1151
1152 /**
1153 * Relevant Generic elements:
1154 * - @c Generic::Text for the header text label
1155 * - @c Generic::ArrowUp @c Generic::ArrowDown to indicate the sorting of the column
1156 *
1157 * [the Sections implement QStyle::CE_HeaderSection]
1158 */
1159 enum Primitive {
1160 SectionHor, ///< header section, horizontal
1161 SectionVert ///< header section, vertical
1162 };
1163 };
1164
1165 /**
1166 * @brief Describes a text edit widget like QLineEdit.
1167 *
1168 * The frame width of lineedits is determined using Generic::DefaultFrameWidth
1169 */
1170 struct LineEdit {
1171 /**
1172 * Relevant Generic elements:
1173 * - @c Generic::Frame paints a lineedit frame only [implements QStyle::PE_FrameLineEdit]
1174 *
1175 * @sa drawKStylePrimitive()
1176 */
1177 enum Primitive {
1178 Panel ///< the panel for a QLineEdit (including frame...) [implements QStyle::PE_PanelLineEdit]
1179 };
1180 };
1181
1182 /**
1183 * @brief Describes something like QGroupBox.
1184 *
1185 * Relevant Generic elements:
1186 * - @c Generic::Frame frame around the group box
1187 *
1188 * [the Frames implement QStyle::PE_FrameGroupBox]
1189 *
1190 * @sa Generic::DefaultFrameWidth
1191 *
1192 * @sa WT_GroupBox
1193 */
1194 struct GroupBox {
1195 /**
1196 * @sa setWidgetLayoutProp()
1197 */
1198 enum LayoutProps {
1199 FrameWidth, /**< (\b 2) width of a groupbox frame */
1200 TextAlignTop, /**< (\b 0) set to non-zero, the title will be aligned
1201 * above the groupbox frame, not vertically centered
1202 * [sets QStyle::SH_GroupBox_TextLabelVerticalAlignment] */
1203 TitleTextColor ///< (\b ColorMode(QPalette::Text)) color of the title text label
1204 };
1205 /**
1206 * @sa drawKStylePrimitive()
1207 */
1208 enum Primitive {
1209 FlatFrame /**< For groupboxes which are set to be 'flat' (usually
1210 * a divider line from top left to top right). K4Style
1211 * has a basic default implementation */
1212 };
1213 };
1214
1215 /**
1216 * @brief Describes a status bar section.
1217 *
1218 * Relevant Generic elements:
1219 * - @c Generic::Frame paints the status bar section [implements QStyle::PE_FrameStatusBar]
1220 *
1221 * No LayoutProps for now.
1222 *
1223 * @sa WT_StatusBar
1224 */
1225 struct StatusBar {
1226 /**
1227 No LayoutProps for now.
1228 */
1229 };
1230
1231 /**
1232 * @brief Describes a tool bar.
1233 *
1234 * @sa WT_ToolBar
1235 */
1236 struct ToolBar {
1237 /**
1238 * @sa setWidgetLayoutProp()
1239 */
1240 enum LayoutProps {
1241 HandleExtent, ///< (\b 6) the width(hor)/height(vert) of a ToolBar handle [sets QStyle::PM_ToolBarHandleExtent]
1242 SeparatorExtent, ///< (\b 6) the width/height of a ToolBar separator [sets QStyle::PM_ToolBarSeparatorExtent]
1243 ExtensionExtent, ///< (\b 10) the width/height of a ToolBar extender, when there is not enough room for toolbar buttons [sets PM_ToolBarExtensionExtent]
1244 FrameWidth, /**< (\b 2) width of the frame around toolbars
1245 * [sets QStyle::PM_ToolBarFrameWidth] */
1246 ItemMargin, ///< (\b 1) [sets QStyle::PM_ToolBarItemMargin]
1247 ItemSpacing ///< (\b 3) [sets QStyle::PM_ToolBarItemSpacing]
1248 };
1249
1250 /**
1251 * [the Handles implement QStyle::PE_IndicatorToolBarHandle]
1252 * [the Panels implement QStyle::CE_ToolBar]
1253 *
1254 * @sa drawKStylePrimitive()
1255 */
1256 enum Primitive {
1257 HandleHor, ///< handle of a toolbar, horizontal
1258 HandleVert, ///< handle of a toolbar, vertical
1259 Separator, ///< [implements QStyle::PE_IndicatorToolBarSeparator]
1260 PanelHor, ///< the actual toolbar, horizontal
1261 PanelVert ///< the actual toolbar, vertical
1262 };
1263 };
1264
1265 /**
1266 * @brief Describes a tab for a tool box, like QToolBox.
1267 *
1268 * @sa WT_ToolBoxTab
1269 */
1270 struct ToolBoxTab {
1271 /**
1272 * @sa setWidgetLayoutProp()
1273 */
1274 enum LayoutProps {
1275 Margin /**< (\b 0) used to specify the
1276 * position of the tab contents, doesn't influence the tab size
1277 * [sets QStyle::SE_ToolBoxTabContents] */
1278 };
1279
1280 /**
1281 * @sa drawKStylePrimitive()
1282 */
1283 enum Primitive {
1284 Panel /**< the panel of a toolbox tab, K4Style default implementation
1285 * paints WT_ToolButton/ToolButton::Panel
1286 * [implements CE_ToolBoxTab] */
1287 };
1288 };
1289
1290 /**
1291 * @brief Describes widgets like QToolButton (usually inside a QToolBar).
1292 * The drawing of ToolButton's is much like that of PushButtons; however, in some cases the widget is configured
1293 * to not have a separate arrow area, but to incorporate the area inside the button itself. To handle this mode,
1294 * set InlineMenuIndicatorSize to the size of the arrow,
1295 * and the InlineMenuIndicatorXOff, and InlineMenuIndicatorYOff to offset from the bottom-right corner to place that
1296 * rectangle. If InlineMenuIndicatorSize isn't set, the arrow won't be drawn.
1297 *
1298 * @sa WT_ToolButton
1299 */
1300 struct ToolButton {
1301 /**
1302 * @sa setWidgetLayoutProp()
1303 */
1304 enum LayoutProps {
1305 ContentsMargin, /**< (\b 5) Margin reserved around the contents size of
1306 * a toolbutton. Used to size the contents. */
1307 FocusMargin = ContentsMargin + MarginInc,
1308 /**< (\b 3) Where the focus rect will be drawn, measured
1309 * from the widget sides */
1310 MenuIndicatorSize, /**< (\b 11) Size for the separate menu arrows on tool buttons
1311 * [sets QStyle::PM_MenuButtonIndicator wheen a toolbutton option is passed in] */
1312 InlineMenuIndicatorSize = FocusMargin + MarginInc, /**< (\b 0) Size of arrow when it's incorporated into
1313 * the button directly. If it's 0, it will not be drawn
1314 * @since 4.1 */
1315 InlineMenuIndicatorXOff, /**< Horizontal offset off the bottom-right corner to place the arrow
1316 * if it's incorporated directly, and not in a separate area
1317 * @since 4.1 */
1318 InlineMenuIndicatorYOff /**< Vertical offset off the bottom-right corner to place the arrow
1319 * if it's incorporated directly, and not in a separate area
1320 * @since 4.1 */
1321 };
1322
1323 /**
1324 * Relevant Generic elements:
1325 * - @c Generic::ArrowDown indicating an associated sub-menu
1326 *
1327 * @todo Implement CE_ToolButtonLabel to have own Generic::Text, Generic::Icon,
1328 * and LayoutProps PressedShiftHorizontal, PressedShiftVertical,
1329 * TextToIconSpace, MenuIndicatorSize...
1330 *
1331 * @sa drawKStylePrimitive()
1332 */
1333 enum Primitive {
1334 Panel /**< the toolbutton panel
1335 * [implements QStyle::PE_PanelButtonTool] */
1336 };
1337 };
1338
1339 /**
1340 * @brief Describes windows, like in QWorkspace.
1341 *
1342 * @todo SP_TitleBar* pixmaps
1343 *
1344 * @sa WT_Window
1345 */
1346 struct Window {
1347 /**
1348 * @sa setWidgetLayoutProp()
1349 */
1350 enum LayoutProps {
1351 TitleTextColor, ///< (\b ColorMode(QPalette::HighlightedText)) color mode of the titlebar text
1352 TitleHeight, ///< (\b 20) height of the titlebar [sets QStyle::PM_TitleBarHeight]
1353 NoTitleFrame, /**< (\b 0) if set to non-zero, the frame primitive is not
1354 * expected to paint around the titlebar area
1355 * [sets QStyle::SH_TitleBar_NoBorder] */
1356 TitleMargin, /**< (\b 2) margin around titlebar contents (buttons,
1357 * text label), used to position them and determine the
1358 * height of titlebar buttons, doesn't influence size */
1359 ButtonWidth = TitleMargin + MarginInc, ///< (\b 16) width of a titlebar button
1360 ButtonSpace, ///< (\b 2) space between titlebar buttons
1361 ButtonToTextSpace ///< (\b 3) space between buttons and the title text
1362 };
1363
1364 /**
1365 * Relevant Generic elements:
1366 * - @c Generic::Text paints the titlebar text label
1367 * - @c Generic::Frame indicating an associated sub-menu
1368 *
1369 * [titlebar elements implement CC_TitleBar]
1370 *
1371 * @sa drawKStylePrimitive()
1372 */
1373 enum Primitive {
1374 TitlePanel, ///< whole titlebar panel/background, by K4Style default it's filled with plain highlight color
1375 ButtonMenu, ///< system menu button, passes TitleButtonOption
1376 ButtonMin, ///< minimize button, passes TitleButtonOption
1377 ButtonMax, ///< maximize button, passes TitleButtonOption
1378 ButtonRestore, ///< restore button, passes TitleButtonOption @todo split min/max restore?
1379 ButtonClose, ///< close button, passes TitleButtonOption
1380 ButtonShade, ///< shade button, passes TitleButtonOption
1381 ButtonUnshade, ///< button to remove the shade state, passes TitleButtonOption
1382 ButtonHelp ///< context help button, passes TitleButtonOption
1383 };
1384 };
1385 //@}
1386
1387 ///Interface for the style to configure various metrics that K4Style has customizable.
1388 void setWidgetLayoutProp(WidgetType widget, int metric, int value);
1389
1390 /**
1391 * @brief Used to obtain information about K4Style layout properties and metrics.
1392 *
1393 * The default implementation returns values which are set
1394 * using setWidgetLayoutProp(), so normally it's not necessary to implement
1395 * it yourself.
1396 *
1397 * @note This method is not meant to be accessible from outside K4Style.
1398 *
1399 * @param widgetType the widget type context where the @p metric property belongs to
1400 * @param metric the value of this property is requested
1401 * @param opt Qt option parameters
1402 * @param w the actual widget this call is related to
1403 */
1404 virtual int widgetLayoutProp(WidgetType widgetType, int metric,
1405 const QStyleOption *opt = nullptr, const QWidget *w = nullptr) const;
1406
1407 /**
1408 * @brief Draws primitives which are used inside K4Style.
1409 *
1410 * K4Style implements various elements of QStyle::ComplexControl
1411 * and QStyle::ControlElement for convenience. Usually complex drawing is
1412 * split into smaller pieces, which can be text, icons, or other K4Style primitives.
1413 * These are painted by this method.
1414 *
1415 * Common Qt option parameters are unpacked for convenience, and information
1416 * from K4Style are passed as a KStyleOption.
1417 *
1418 * @note This method is not meant to be accessible from outside K4Style.
1419 * @note You should make sure to use the @p r parameter for the rectangle,
1420 * since the QStyleOption is generally unaltered from the original request,
1421 * even if layout indicates a different painting rectangle.
1422 *
1423 * @param widgetType the widget context in which this call is happening in
1424 * @param primitive the primitive which should be called. Primitives from the Generic
1425 * struct are not directly coupled to the @p widgetType , other primitives are usually
1426 * defined in the struct corresponding to the widget type.
1427 * @param opt Qt option parameters
1428 * @param r parameter for the rectangle
1429 * @param pal the palette extracted from @p opt for convenience
1430 * @param flags state flags extracted from @p opt for convenience
1431 * @param p used to draw the primitive
1432 * @param widget the widget which is painted on
1433 * @param kOpt information passed from K4Style
1434 */
1435 virtual void drawKStylePrimitive(WidgetType widgetType, int primitive,
1436 const QStyleOption *opt,
1437 const QRect &r, const QPalette &pal,
1438 State flags, QPainter *p,
1439 const QWidget *widget = nullptr,
1440 Option *kOpt = nullptr) const;
1441 private:
1442 ///Should we use a side text here?
1443 bool useSideText(const QStyleOptionProgressBar *opt) const;
1444 int sideTextWidth(const QStyleOptionProgressBar *pbOpt) const;
1445
1446 ///Returns true if the tab is vertical
1447 bool isVerticalTab(const QStyleOptionTab *tbOpt) const;
1448
1449 ///Returns true if the tab has reflected layout
1450 bool isReflectedTab(const QStyleOptionTab *tbOpt) const;
1451
1452 enum Side {
1453 North,
1454 East,
1455 West,
1456 South
1457 };
1458
1459 Side tabSide(const QStyleOptionTab *tbOpt) const;
1460
1461 ///Returns the tab rectangle adjusted for the tab direction
1462 QRect marginAdjustedTab(const QStyleOptionTab *tbOpt, int property) const;
1463
1464 ///Wrapper around visualRect for easier use
1465 QRect handleRTL(const QStyleOption *opt, const QRect &subRect) const;
1466 QPoint handleRTL(const QStyleOption *opt, const QPoint &pos) const;
1467
1468 ///Storage for metrics/flags
1469 QVector<QVector<int> > metrics;
1470
1471 ///Expands out the dimension to make sure it incorporates the margins
1472 QSize expandDim(const QSize &orig, WidgetType widget, int baseMarginMetric, const QStyleOption *opt, const QWidget *w, bool rotated = false) const;
1473
1474 ///Calculates the contents rectangle by subtracting out the appropriate margins
1475 ///from the outside
1476 QRect insideMargin(const QRect &orig, WidgetType widget, int baseMarginMetric, const QStyleOption *opt, const QWidget *w) const;
1477
1478 ///Internal subrect calculations, for e.g. scrollbar arrows,
1479 ///where we fake our output to get Qt to do what we want
1480 QRect internalSubControlRect(ComplexControl control, const QStyleOptionComplex *opt,
1481 SubControl subControl, const QWidget *w) const;
1482
1483 // fitt's law label support: QLabel focusing its buddy widget
1484 const QObject *clickedLabel;
1485
1486 public:
1487 /** @name QStyle Methods
1488 * These are methods reimplemented from QStyle. Usually it's not necessary to
1489 * reimplement them yourself.
1490 *
1491 * Some of them are there for binary compatibility reasons only; all they do is to call
1492 * the implementation from QCommonStyle.
1493 */
1494 //@{
1495 void drawControl(ControlElement elem, const QStyleOption *opt, QPainter *p, const QWidget *w) const override;
1496 void drawPrimitive(PrimitiveElement elem, const QStyleOption *opt, QPainter *p, const QWidget *w) const override;
1497 int pixelMetric(PixelMetric metric, const QStyleOption *opt = nullptr, const QWidget *w = nullptr) const override;
1498 QRect subElementRect(SubElement subRect, const QStyleOption *opt, const QWidget *w) const override;
1499 QSize sizeFromContents(ContentsType type, const QStyleOption *opt,
1500 const QSize &contentsSize, const QWidget *w) const override;
1501 int styleHint(StyleHint hint, const QStyleOption *opt, const QWidget *w,
1502 QStyleHintReturn *returnData) const override;
1503 QRect subControlRect(ComplexControl control, const QStyleOptionComplex *opt,
1504 SubControl subControl, const QWidget *w) const override;
1505 SubControl hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt,
1506 const QPoint &pt, const QWidget *w) const override;
1507 void drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt,
1508 QPainter *p, const QWidget *w) const override;
1509
1510 void polish(QWidget *) override;
1511 void unpolish(QWidget *) override;
1512 void polish(QApplication *) override;
1513 void unpolish(QApplication *) override;
1514 void polish(QPalette &) override;
1515 QRect itemTextRect(const QFontMetrics &fm, const QRect &r,
1516 int flags, bool enabled,
1517 const QString &text) const override;
1518 QRect itemPixmapRect(const QRect &r, int flags, const QPixmap &pixmap) const override;
1519 void drawItemText(QPainter *painter, const QRect &rect,
1520 int flags, const QPalette &pal, bool enabled,
1521 const QString &text, QPalette::ColorRole textRole = QPalette::NoRole) const override;
1522 void drawItemPixmap(QPainter *painter, const QRect &rect,
1523 int alignment, const QPixmap &pixmap) const override;
1524 QPalette standardPalette() const override;
1525 QPixmap standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt,
1526 const QWidget *widget = nullptr) const override; //### kde5 remove
1527 QPixmap generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap,
1528 const QStyleOption *opt) const override;
1529 bool eventFilter(QObject *, QEvent *) override;
1530
1531 int layoutSpacing(QSizePolicy::ControlType control1,
1532 QSizePolicy::ControlType control2, Qt::Orientation orientation,
1533 const QStyleOption *option = nullptr, const QWidget *widget = nullptr) const override;
1534
1535 QIcon standardIcon(StandardPixmap standardIcon, const QStyleOption *option = nullptr,
1536 const QWidget *widget = nullptr) const override;
1537 //@}
1538 private:
1539 K4StylePrivate *const d;
1540 };
1541
1542 template<typename T>
kstyleName()1543 const char *kstyleName()
1544 {
1545 return "default";
1546 }
1547
1548 /**
1549 * Template class which helps implementing the widget style plugin interface.
1550 *
1551 * You don't need to use this class directly. Use the following
1552 * macro (defined in kstyle.h) and you are done:
1553 * \code
1554 * K_EXPORT_STYLE("StyleName", StyleClassName)
1555 * \endcode
1556 */
1557 template<typename T>
1558 class K4StyleFactory: public QStylePlugin
1559 {
keys()1560 QStringList keys() const
1561 {
1562 QStringList l;
1563 l << kstyleName<T>();
1564 return l;
1565 }
1566
create(const QString & id)1567 QStyle *create(const QString &id) override
1568 {
1569 QStringList names = keys();
1570 //check whether included in the keys
1571 if (names.contains(id, Qt::CaseInsensitive)) {
1572 return new T();
1573 }
1574
1575 return nullptr;
1576 }
1577 };
1578
1579 template<typename T>
extractOption(Option * option)1580 T K4Style::extractOption(Option *option)
1581 {
1582 if (option) {
1583 if (dynamic_cast<T>(option)) {
1584 return static_cast<T>(option);
1585 }
1586 // Ugly hacks for when RTLD_GLOBAL is not used (quite common with plugins, really)
1587 // and dynamic_cast fails.
1588 // This is still partially broken as it doesn't take into account subclasses.
1589 // ### KDE5 do this somehow differently
1590 if (qstrcmp(typeid(*option).name(), typeid(typename std::remove_pointer<T>::type).name()) == 0) {
1591 return static_cast<T>(option);
1592 }
1593 }
1594
1595 //### warn if cast failed?
1596
1597 //since T is a pointer type, need this to get to the static.
1598 return static_cast<T>(nullptr)->defaultOption();
1599 }
1600
1601 #define K_EXPORT_K4STYLE(name,type) template<> const char* kstyleName<type>() { return name; } \
1602 Q_EXPORT_PLUGIN(K4StyleFactory<type>)
1603
1604 #endif
1605