Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
styles.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3/*!
4 \page style-reference.html
5 \title Styles and Style Aware Widgets
6 \ingroup qt-gui-concepts
7 \brief Styles and the styling of widgets.
8
9 Styles (classes that inherit QStyle) draw on behalf of widgets
10 and encapsulate the look and feel of a GUI. The QStyle class is
11 an abstract base class that encapsulates the look and feel of a
12 GUI. Qt's built-in widgets use it to perform nearly all of their
13 drawing, ensuring that they look exactly like the equivalent
14 native widgets.
15
16 Qt comes with a selection of built-in styles. Certain styles are only
17 available on specific platforms. Custom styles are made available as
18 plugins or by creating an instance of a specific style class with
19 QStyleFactory::create() and setting it with QApplication::setStyle().
20
21 \section1 Customizing a Style
22
23 In order to customize an existing style, inherit QProxyStyle and
24 reimplement the desired virtual methods. QProxyStyle allows one
25 to specify a certain base style, or it will automatically use the
26 application style when the base style is left unspecified. The
27 former gives a full control on the base style and works best if
28 the customization expects a certain style behavior, whereas the
29 latter provides a platform agnostic way to customize the application
30 style that defaults to the native platform style.
31
32 \section1 Implementing a Custom Style
33
34 QCommonStyle provides a convenient base for full custom style
35 implementations. The approach is same than with QProxyStyle, but
36 inherit QCommonStyle instead and reimplement the appropriate virtual
37 methods. Implementing a full custom style is somewhat involved, and
38 we therefore provide this overview. We give a step-by-step walkthrough
39 of how to style individual Qt widgets. We will examine the QStyle
40 virtual functions, member variables, and enumerations.
41
42 The part of this document that does not concern the styling of
43 individual widgets is meant to be read sequentially because later
44 sections tend to depend on earlier ones. The description of the
45 widgets can be used for reference while implementing a style.
46 However, you may need to consult the Qt source code in some cases.
47 The sequence in the styling process should become clear after
48 reading this document, which will aid you in locating relevant code.
49
50 To develop style aware widgets (i.e., widgets that conform to
51 the style in which they are drawn), you need to draw them using the
52 current style. This document shows how widgets draw themselves
53 and which possibilities the style gives them.
54
55 \section1 Classes for Widget Styling
56
57 These classes are used to customize an application's appearance and
58 style.
59
60 \annotatedlist appearance
61
62 \section1 The QStyle Implementation
63
64 The API of QStyle contains functions that draw the widgets, static
65 helper functions to do common and difficult tasks (e.g.,
66 calculating the position of slider handles) and functions to do
67 the various calculations necessary while drawing (e.g., for the
68 widgets to calculate their size hints). The style also helps some
69 widgets with the layout of their contents. In addition, it creates
70 a QPalette that contains \l{QBrush}es to draw with.
71
72 QStyle draws graphical elements; an element is a widget or a
73 widget part like a push button bevel, a window frame, or a scroll
74 bar. Most draw functions now take four arguments:
75
76 \list
77 \li an enum value specifying which graphical element to draw
78 \li a QStyleOption specifying how and where to render that element
79 \li a QPainter that should be used to draw the element
80 \li a QWidget on which the drawing is performed (optional)
81 \endlist
82
83 When a widget asks a style to draw an element, it provides the style
84 with a QStyleOption, which is a class that contains the information
85 necessary for drawing. Thanks to QStyleOption, it is possible to make
86 QStyle draw widgets without linking in any code for the widget. This
87 makes it possible to use \l{QStyle}'s draw functions on any paint
88 device, i.e., you can draw a combobox on any widget, not just on a
89 QComboBox.
90
91 The widget is passed as the last argument in case the style needs
92 it to perform special effects (such as animated default buttons on
93 \macos), but it isn't mandatory.
94
95 In the course of this section, we will look at the style elements,
96 the style options, and the functions of QStyle. Finally, we describe
97 how the palette is used.
98
99 Items in item views are drawn by \l{Delegate Classes}{delegates} in
100 Qt. The item view headers are still drawn by the style. Qt's
101 default delegate, QStyledItemDelegate, draws its items partially
102 through the current style; it draws the check box indicators and
103 calculates bounding rectangles for the elements of which the item
104 consists. In this document, we only describe how to implement a
105 QStyle subclass. If you wish to add support for other datatypes
106 than those supported by the QStyledItemDelegate, you need to
107 implement a custom delegate. Note that delegates must be set
108 programmatically for each individual widget (i.e., default
109 delegates cannot be provided as plugins).
110
111 \section2 The Style Elements
112
113 A style element is a graphical part of a GUI. A widget consists
114 of a hierarchy (or tree) of style elements. For instance, when a
115 style receives a request to draw a push button (from QPushButton,
116 for example), it draws a label (text and icon), a button bevel,
117 and a focus frame. The button bevel, in turn, consists of a frame
118 around the bevel and two other elements, which we will look at
119 later. Below is a conceptual illustration of the push button
120 element tree. We will see the actual tree for QPushButton when we
121 go through the individual widgets.
122
123 \image javastyle/conceptualpushbuttontree.png
124 {Push button style tree and elements}
125
126 Widgets are not necessarily drawn by asking the style to draw
127 only one element. Widgets can make several calls to the style to
128 draw different elements. An example is QTabWidget, which draws its
129 tabs and frame individually.
130
131 There are three element types: primitive elements, control
132 elements, and complex control elements. The elements are defined
133 by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement},
134 and \l{QStyle::}{PrimitiveElement} enums. The values of
135 each element enum has a prefix to identify their type: \c{CC_} for
136 complex elements, \c{CE_} for control elements, and \c{PE_} for
137 primitive elements. We will in the following three sections see what
138 defines the different elements and see examples of widgets that use
139 them.
140
141 The QStyle class description contains a list of these elements and
142 their roles in styling widgets. We will see how they are used when
143 we style individual widgets.
144
145 \section3 Primitive Elements
146
147 Primitive elements are GUI elements that are common and often used
148 by several widgets. Examples of these are frames, button bevels,
149 and arrows for spin boxes, scroll bars, and combo boxes.
150 Primitive elements cannot exist on their own: they are always part
151 of a larger construct. They take no part in the interaction with
152 the user, but are passive decorations in the GUI.
153
154 \section3 Control Elements
155
156 A control element performs an action or displays information
157 to the user. Examples of control elements are push buttons, check
158 boxes, and header sections in tables and tree views. Control
159 elements are not necessarily complete widgets such as push
160 buttons, but can also be widget parts such as tab bar tabs and
161 scroll bar sliders. They differ from primitive elements in that
162 they are not passive, but fill a function in the interaction with
163 the user. Controls that consist of several elements often use the
164 style to calculate the bounding rectangles of the elements. The
165 available sub elements are defined by the \l{QStyle::}{SubElement}
166 enum. This enum is only used for calculating bounding rectangles;
167 sub elements are not graphical elements to be drawn like primitive,
168 control, and complex elements.
169
170 \section3 Complex Control Elements
171
172 Complex control elements contain sub controls. Complex controls
173 behave differently depending on where the user handles them with
174 the mouse and which keyboard keys are pressed. This is dependent
175 on which sub control (if any) the mouse is over or pressed on.
176 Examples of complex controls are scroll bars and
177 combo boxes. With a scroll bar, you can use the mouse to move the
178 slider and press the line up and line down buttons. The available
179 sub controls are defined by the \l{QStyle}{SubControl} enum.
180
181 In addition to drawing, the style needs to provide the widgets
182 with information on which sub control (if any) a mouse press was
183 made on. For instance, a QScrollBar needs to know if the user
184 pressed the slider, the slider groove, or one of the buttons.
185
186 Note that sub controls are not the same as the control elements
187 described in the previous section. You cannot use the style to
188 draw a sub control; the style will only calculate the bounding
189 rectangle in which the sub control should be drawn. It is common,
190 though, that complex elements use control and primitive elements
191 to draw their sub controls, which is an approach that is
192 frequently used by the built-in styles in Qt and also the Java
193 style. For instance, the Java style uses PE_IndicatorCheckBox to
194 draw the check box in group boxes (which is a sub control of
195 \c CC_GroupBox). Some sub controls have an equivalent control element,
196 e.g., the scroll bar slider (\c SC_SCrollBarSlider and
197 \c CE_ScrollBarSlider).
198
199 \section3 Other QStyle Tasks
200
201 The style elements and widgets, as mentioned, use the style to
202 calculate bounding rectangles of sub elements and sub controls.
203 Pixel metrics, which are style-dependent sizes in screen
204 pixels, are also used for measurements when drawing. The available
205 rectangles and pixel metrics are represented by three enums in
206 QStyle: \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and
207 \l{QStyle::}{PixelMetric}. Values of the enums can easily by
208 identified as they start with SE_, SC_ and PM_.
209
210 The style also contains a set of style hints, which is
211 represented as values in the \l{QStyle::}{StyleHint} enum. All
212 widgets do not have the same functionality and look in the
213 different styles. For instance, when the menu items in a menu do not
214 fit in a single column on the screen, some styles support
215 scrolling while others draw more than one column to fit all items.
216
217 A style usually has a set of standard images (such as a warning, a
218 question, and an error image) for message boxes, file dialogs,
219 etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its
220 values represent the standard images. Qt's widgets use these, so
221 when you implement a custom style you should supply the images
222 used by the style that is being implemented.
223
224 The style calculates the spacing between widgets in layouts. There
225 are two ways the style can handle these calculations. You can set
226 the \c PM_LayoutHorizontalSpacing and \c PM_LayoutVerticalSpacing, which
227 is the way the Java style does it (through QCommonStyle).
228 Alternatively, you can implement QStyle::layoutSpacing() and
229 QStyle::layoutSpacingImplementation() if you need more control over
230 this part of the layout. In these functions you can calculate the
231 spacing based on control types (QSizePolicy::ControlType) for
232 different size policies (QSizePolicy::Policy) and also the style
233 option for the widget in question.
234
235 \section2 Style Options
236
237 The sub-classes of QStyleOption contain all information necessary
238 to style the individual elements. Style options are instantiated -
239 usually on the stack - and filled out by the caller of the QStyle
240 function. Depending on what is drawn the style will expect
241 different a different style option class. For example, the
242 \c QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect
243 argument, and it's possible to create custom subclasses that a
244 custom style can use. The style options keep public variables
245 for performance reasons.
246
247 The widgets can be in a number of different states, which are
248 defined by the \l{QStyle::}{State} enum. Some of the state flags have
249 different meanings depending on the widget, but others are common
250 for all widgets like \c State_Disabled. It is QStyleOption that sets
251 the common states with QStyleOption::initFrom(); the rest of the
252 states are set by the individual widgets.
253
254 Most notably, the style options contain the palette and bounding
255 rectangles of the widgets to be drawn. Most widgets have
256 specialized style options. QPushButton and QCheckBox, for
257 instance, use QStyleOptionButton as their style option, which contains
258 the text, icon, and the size of their icon. The exact contents of
259 all options are described when we go through the individual widgets.
260
261 When reimplementing QStyle functions that take a
262 QStyleOption parameter, you often need to cast the
263 QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For
264 safety, you can use qstyleoption_cast() to ensure that the
265 pointer type is correct. If the object isn't of the right type,
266 qstyleoption_cast() returns \nullptr. For example:
267
268 \snippet code/doc_src_qt4-styles.cpp 0
269
270 The following code snippet illustrates how to use QStyle to
271 draw the focus rectangle from a custom widget's paintEvent():
272
273 \snippet code/doc_src_qt4-styles.cpp 1
274
275 The next example shows how to derive from an existing style to
276 customize the look of a graphical element:
277
278 \snippet customstyle/customstyle.h 0
279 \codeline
280 \snippet customstyle/customstyle.cpp 2
281
282 \section2 QStyle Functions
283
284 The QStyle class defines three functions for drawing the primitive,
285 control, and complex elements:
286 \l{QStyle::}{drawPrimitive()},
287 \l{QStyle::}{drawControl()}, and
288 \l{QStyle::}{drawComplexControl()}. The functions takes the
289 following parameters:
290
291 \list
292 \li the enum value of the element to draw.
293 \li a QStyleOption which contains the information needed to
294 draw the element.
295 \li a QPainter with which to draw the element.
296 \li a pointer to a QWidget, typically the widget
297 that the element is painted on.
298 \endlist
299
300 Not all widgets send a pointer to themselves. If the style
301 option sent to the function does not contain the information you
302 need, you should check the widget implementation to see if it
303 sends a pointer to itself.
304
305 The QStyle class also provides helper functions that are used
306 when drawing the elements. The \l{QStyle::}{drawItemText()}
307 function draws text within a specified rectangle, taking a
308 QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()}
309 function helps to align a pixmap within a specified bounding
310 rectangle.
311
312 Other QStyle functions do various calculations for the
313 functions that do drawing. The widgets also use these functions for
314 calculating size hints and bounding rectangles if they draw several
315 style elements themselves. As with the functions that draw elements,
316 the helper functions typically take the same arguments.
317
318 \list
319 \li The \l{QStyle::}{subElementRect()} function takes a
320 \l{QStyle::}{SubElement} enum value and calculates a bounding
321 rectangle for a sub element. The style uses this function to
322 know where to draw the different parts of an element. This is
323 mainly done for reuse; if you create a new style, you can use
324 the same location of sub elements as the super class.
325
326 \li The \l{QStyle::}{subControlRect()} function is used to
327 calculate bounding rectangles for sub controls in complex
328 controls. When you implement a new style, you reimplement \c
329 subControlRect() and calculate the rectangles that are different
330 from the super class.
331
332 \li The \l{QStyle::}{pixelMetric()} function returns a pixel
333 metric, which is a style-dependent size given in screen
334 pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum
335 and returns the correct measurement. Note that pixel metrics do
336 not necessarily have to be static measurements, but can be
337 calculated with, for example, the style option.
338
339 \li The \l{QStyle::}{hitTestComplexControl()} function returns the
340 sub control that the mouse pointer is over in a complex control.
341 Usually, this is simply a matter of using
342 \l{QStyle::}{subControlRect()} to get the bounding rectangles of
343 the sub controls, and then seeing which rectangle contains the
344 position of the cursor.
345 \endlist
346
347 QStyle also has the functions \l{QStyle::}{polish()} and
348 \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish()
349 function before being shown and to \c unpolish() when they
350 are hidden. You can use these functions to set attributes on the
351 widgets or do other work that is required by your style. For
352 instance, if you need to know when the mouse is hovering over the
353 widget, you need to set the \l{Qt::}{WA_Hover} widget attribute.
354 The \c State_MouseOver state flag will then be set in the widget's
355 style options.
356
357 QStyle has a few static helper functions that do some common and
358 difficult tasks. They can calculate the position of a slider
359 handle from the value of the slider and transform rectangles
360 and draw text considering reverse layouts; see the QStyle
361 class documentation for more details.
362
363 The usual approach when one reimplements QStyle virtual
364 functions is to do work on elements that are different from the
365 super class; for all other elements, you can simply use the super
366 class implementation.
367
368 \section2 The Palette
369
370 Each style provides a color - that is, QBrush - palette that
371 should be used for drawing the widgets. There is one set of colors
372 for the different widget states (QPalette::ColorGroup): active
373 (widgets in the window that have keyboard focus), inactive (widgets
374 used for other windows), and disabled (widgets that are disabled).
375 The states can be found by querying the \c State_Active
376 and \c State_Enabled state flags. Each set contains certain color
377 roles given by the QPalette::ColorRole enum. The roles describe in
378 which situations the colors should be used (e.g., for painting
379 widget backgrounds, text, or buttons).
380
381 How the color roles are used is up to the style. For instance, if
382 the style uses gradients, one can use a palette color and make it
383 darker or lighter with QColor::darker() and QColor::lighter() to
384 create the gradient. In general, if you need a brush that is not
385 provided by the palette, you should try to derive it from one.
386
387 QPalette, which provides the palette, stores colors for
388 different widget states and color roles. The palette for a style
389 is returned by \l{QStyle::}{standardPalette()}. The standard
390 palette is not installed automatically when a new style is set
391 on the application (QApplication::setStyle()) or widget
392 (QWidget::setStyle()), so you must set the palette yourself
393 with (QApplication::setPalette()) or (QWidget::setPalette()).
394
395 It is not recommended to hard-code colors, as applications and
396 individual widgets can set their own palette and also use their
397 style's palette for drawing. Note that none of Qt's widgets set
398 their own palette. The Java style does hard-code some colors, but
399 only as a decision of the author; it is not advised. Of course,
400 it is not intended that the style should look good with any palette.
401
402 \section2 Implementation Issues
403
404 When you implement styles, there are several issues to
405 consider. We will give some hints and advice on implementation
406 here.
407
408 When implementing styles, it is necessary to look through the
409 code of the widgets and code of the base class and its ancestors.
410 This is because the widgets use the style differently, because the
411 implementation in the different styles' virtual functions can
412 affect the state of the drawing (e.g., by altering the QPainter
413 state without restoring it and drawing some elements without using
414 the appropriate pixel metrics and sub elements).
415
416 It is recommended that the styles do not alter the proposed size
417 of widgets with the QStyle::sizeFromContents() function, but let
418 the QCommonStyle implementation handle it instead. If changes need
419 to be made, you should try to keep them small; application development
420 may be difficult if the layout of widgets looks considerably
421 different in the various styles.
422
423 \section1 Java Style
424
425 We have implemented a style that resembles the Java default look
426 and feel (previously known as Metal). We have done this as it is
427 relatively simple to implement and we wanted to build a style for
428 this overview document. To keep it simple and not too extensive, we
429 have simplified the style somewhat, but Qt is perfectly able to
430 make an exact copy of the style. However, there are no concrete
431 plans to implement the style as a part of Qt.
432
433 In this section we will have a look at some implementation
434 issues. Finally, we will see a complete example on the styling of
435 a Java widget. We will continue to use the Java style
436 throughout the document for examples and widget images. The
437 implementation itself is somewhat involved, and it is not
438 intended that you should read through it.
439
440 \section2 Design and Implementation
441
442 The first step in designing the style was to select the base
443 class. We chose to subclass QCommonStyle. This class implements
444 most of the functionality we need, other than performing the actual
445 drawing.
446
447 The style is implemented in one class. We have done this
448 because we find it convenient to keep all code in one file. Also,
449 it is an advantage with regards to optimization as we instantiate
450 less objects. We also keep the number of functions at a minimum by
451 using switches to identify which element to draw in the functions.
452 This results in large functions, but since we divide the code for
453 each element in the switches, the code should still be easy to
454 read.
455
456 \section2 Limitations and Differences from Java
457
458 We have not fully implemented every element in the Java style.
459 This way, we have reduced the amount and complexity of the code.
460 In general, the style was intended as a practical example for
461 this style overview document, and not to be a part of Qt
462 itself.
463
464 Not all widgets have every state implemented. This goes for
465 states that are common, e.g., \c State_Disabled. Each state is,
466 however, implemented for at least one widget.
467
468 We have only implemented ticks below the slider. Flat push
469 buttons are also left out. We do not handle the case where the
470 title bars and dock window titles grow too small for their
471 contents, but simply draw sub controls over each other.
472
473 We have not tried to emulate the Java fonts. Java and Qt use very
474 different font engines, so we don't consider it worth the effort
475 as we only use the style as an example for this overview.
476
477 We have hard-coded the colors (we don't use the QPalette) for
478 the linear gradients, which are used, for example, for button
479 bevels, tool bars, and check boxes. This is because the Java
480 palette cannot produce these colors. Java does not change these
481 colors based on widget color group or role anyway (they are not
482 dependent on the palette), so it does not present a problem in any
483 case.
484
485 It is Qt's widgets that are styled. Some widgets do not exist
486 at all in Java, e.g., QToolBox. Others contain elements that the
487 Java widgets don't. The tree widget is an example of the latter in
488 which Java's JTree does not have a header.
489
490 The style does not handle reverse layouts. We assume that the
491 layout direction is left to right. QCommonStyle handles reverse
492 widgets; if we implemented reverse layouts, widgets that we change
493 the position of sub elements, or handle text alignment in labels
494 ourselves would need to be updated.
495
496 \section2 Styling Java Check Boxes
497
498 As an example, we will examine the styling of check boxes in the
499 Java style. We describe the complete process and print all code in
500 both the Java style and Qt classes involved. In the rest of this
501 document, we will not examine the source code of the individual
502 widgets. Hopefully, this will give you an idea on how to search
503 through the code if you need to check specific implementation
504 details; most widgets follow the same structure as the check
505 boxes. We have edited the QCommonStyle code somewhat to remove
506 code that is not directly relevant for check box styling.
507
508 We start with a look at how QCheckBox builds its style option,
509 which is QStyleOptionButton for checkboxes:
510
511 \snippet code/doc_src_styles.cpp 0
512
513 First we let QStyleOption set up the option with the information
514 that is common for all widgets with \c initFrom(). We will look at
515 this shortly.
516
517 QStyleOption's \c down variable is \c true when the user presses the box down;
518 this is true of the checkbox whether the box is checked or not. The
519 \c State_NoChange state is set when we have a tri-state checkbox and
520 it is partially checked. It has \c State_On if the box is checked and
521 \c State_Off if it is unchecked. \c State_MouseOver is set if the mouse
522 hovers over the checkbox and the widget has attribute \c Qt::WA_Hover
523 set - you set this in QStyle::polish(). In addition, the style
524 option also contains the text, icon, and icon size of the button.
525
526 \l{QStyleOption::}{initFrom()} sets up the style option with the
527 attributes that are common for all widgets. We print its
528 implementation here:
529
530 \snippet code/doc_src_styles.cpp 1
531
532 The \c State_Enabled is set when the widget is enabled. When the
533 widget has focus the \c State_HasFocus flag is set. Equally, the
534 \c State_Active flag is set when the widget is a child of the active
535 window. The \c State_MouseOver will only be set if the widget has
536 the \c WA_HoverEnabled windows flag set.
537
538 In addition to setting state flags the QStyleOption contains
539 other information about the widget: \c direction is the layout
540 direction of the layout, \c rect is the bounding rectangle of the
541 widget (the area in which to draw), \c palette is the QPalette
542 that should be used for drawing the widget, and \c fontMetrics is
543 the metrics of the font that is used by the widget.
544
545 We give an image of a checkbox and the style option to match
546 it.
547
548 \image javastyle/checkboxexample.png {Checkbox using the Java style}
549
550 The above checkbox will have the following state flags in its
551 style option:
552
553 \table 90%
554 \header
555 \li State flag
556 \li Set
557 \row
558 \li \c State_Sunken
559 \li Yes
560 \row
561 \li \c State_NoChange
562 \li No
563 \row
564 \li \c State_On
565 \li Yes
566 \row
567 \li \c State_Off
568 \li No
569 \row
570 \li \c State_MouseOver
571 \li Yes
572 \row
573 \li \c State_Enabled
574 \li Yes
575 \row
576 \li \c State_HasFocus
577 \li Yes
578 \row
579 \li \c State_KeyboardFocusChange
580 \li No
581 \row
582 \li \c State_Active
583 \li Yes
584 \endtable
585
586 The QCheckBox paints itself in QWidget::paintEvent() with
587 style option \c opt and QStylePainter \c p. The QStylePainter
588 class is a convenience class to draw style elements. Most
589 notably, it wraps the methods in QStyle used for painting. The
590 QCheckBox draws itself as follows:
591
592 \snippet code/doc_src_styles.cpp 2
593
594 QCommonStyle handles the CE_CheckBox element. The QCheckBox
595 has two sub elements: SE_CheckBoxIndicator (the checked indicator)
596 and SE_CheckBoxContents (the contents, which are used for the
597 checkbox label). QCommonStyle also implements these sub element
598 bounding rectangles. Next, we'll have a look at the QCommonStyle code:
599
600 \snippet code/doc_src_styles.cpp 3
601
602 As can be seen from the code extract, the common style gets
603 the bounding rectangles of the two sub elements of
604 CE_CheckBox, and then draws them. If the checkbox has focus,
605 the focus frame is also drawn.
606
607 The Java style draws CE_CheckBoxIndicator, while QCommonStyle
608 handles CE_CheckboxLabel. We will examine each implementation and
609 start with CE_CheckBoxLabel:
610
611 \snippet code/doc_src_styles.cpp 4
612
613 \l{QStyle::}{visualAlignment()} adjusts the alignment of text
614 according to the layout direction. We then draw an icon if it
615 exists, and adjust the space left for the text.
616 \l{QStyle::}{drawItemText()} draws the text, taking alignment,
617 layout direction, and the mnemonic into account. It also uses the
618 palette to draw the text in the right color.
619
620 The drawing of labels often gets somewhat involved. Luckily, it
621 can usually be handled by the base class. The Java style
622 implements its own push button label, since Java centers button
623 contents also when the button has an icon. You can examine that
624 implementation if you need an example of reimplementing label
625 drawing.
626
627 We'll now take a look at the Java implementation
628 of CE_CheckBoxIndicator in \c drawControl():
629
630 \snippet javastyle.cpp 0
631
632 We first save the state of the painter. This is not always
633 necessary, but in this case the QCommonStyle needs the painter in
634 the same state as it was when PE_IndicatorCheckBox was called (We
635 could also set the state with function calls, of course). We then
636 use \c drawButtonBackground() to draw the background of the check
637 box indicator. This is a helper function that draws the background
638 and also the frame of push buttons and check boxes. We take a look
639 at that function below. We then check if the mouse is hovering
640 over the checkbox. If it is, we draw the frame that Java checkboxes
641 have when the box is not pressed down and the mouse is over it.
642 You may note that Java does not handle tri-state boxes, so we have
643 not implemented it.
644
645 Here we use a PNG image for our indicator. We could also check
646 if the widget is disabled. We would then have to use
647 another image with the indicator in the disabled color.
648
649 \snippet javastyle.cpp 1
650
651 We have seen how check boxes are styled in the Java style from the
652 time the widget gets a paint request to the time the style is
653 finished painting. To learn in detail how each widget is painted,
654 you need to go through the code step-by-step as we have done here.
655 However, it is usually enough to know which style elements the
656 widgets draw. The widget builds a style option and calls on the
657 style one or more times to draw the style elements of which it
658 consists. Usually, it is also sufficient to know the states a widget
659 can be in and the other contents of the style option, i.e., what we
660 list in the next section.
661
662 \section1 Widget Walkthrough
663
664 In this section, we will examine how most of Qt's widgets are
665 styled. Hopefully, this will save you some time and effort while
666 developing your own styles and widgets. You will not find
667 information here that is not attainable elsewhere (i.e., by
668 examining the source code or the class descriptions for the style
669 related classes).
670
671 We mostly use Java style widgets as examples. The Java style does not
672 draw every element in the element trees. This is because they are
673 not visible for that widget in the Java style. We still make sure
674 that all elements are implemented in a way that conforms with the
675 Java style, as custom widgets might need them (this does not
676 exclude leaving implementations to QCommonStyle though).
677
678 The following is given for each widget:
679
680 \list
681 \li A table with the members (variables, etc.) of its style option.
682 \li A table of the state flags (QStyle::StateFlag) that
683 can be set on the widget and when the states are set.
684 \li Its element tree (see section \l{The Style Elements}).
685 \li An image of the widget in which the elements are outlined.
686 \omit This is not written yet - probably never will be
687 either
688 \li A list of style hints that should be checked for the
689 widget.
690 \li A list of standard pixmaps that could be used by the
691 elements.
692 \endomit
693 \endlist
694
695 The element tree contains the primitive, control, and complex
696 style elements. By doing a top-down traversal of the element tree,
697 you get the sequence in which the elements should be drawn. In the
698 nodes, we have written the sub element rectangles, sub control
699 elements, and pixel metrics that should be considered when drawing
700 the element of the node.
701
702 Our approach on styling centers on the drawing of the widgets. The
703 calculations of sub elements rectangles, sub controls, and pixel
704 metrics used \b during drawing is only listed as contents in
705 the element trees. Note that there are rectangles and pixel
706 metrics that are only used by widgets. This leaves these
707 calculations untreated in the walkthrough. For instance, the
708 \l{QStyle::}{subControlRect()} and
709 \l{QStyle::}{sizeFromContents()} functions often call
710 \l{QStyle::}{subElementRect()} to calculate their bounding
711 rectangles. We could draw trees for this as well. However, how
712 these calculations are done is completely up to the individual
713 styles, and they do not have to follow a specific structure (Qt
714 does not impose a specific structure). You should still make sure
715 that you use the appropriate pixel metrics, though. To limit the
716 size of the document, we have therefore chosen not to include
717 trees or describe the calculations made by the Java (or any other)
718 style.
719
720 You may be confused about how the different pixel metrics, sub
721 element rectangles, and sub control rectangles should be used when
722 examining the trees. If you are in doubt after reading the QStyle
723 enum descriptions, we suggest that you examine the QCommonStyle
724 implementation.
725
726 Some of the bounding rectangles that we outline in the widget
727 images are equal. Reasons for this are that some elements draw
728 backgrounds while others draw frames and labels. If in doubt,
729 check the description of each element in QStyle. Also, some
730 elements are there to layout, i.e., decide where to draw, other
731 elements.
732
733 \section2 Common Widget Properties
734
735 Some states and variables are common for all widgets. These are
736 set with QStyleOption::initFrom(). Not all elements use this function;
737 it is the widgets that create the style options, and for some
738 elements the information from \l{QStyleOption::}{initFrom()} is not
739 necessary.
740
741 A table with the common states follows:
742
743 \table 90%
744 \header
745 \li State
746 \li State Set When
747 \row
748 \li \c State_Enabled
749 \li Set if the widget is not disabled (see
750 QWidget::setEnabled())
751 \row
752 \li \c State_Focus
753 \li Set if the widget has focus (see
754 QWidget::hasFocus())
755 \row
756 \li \c State_KeyboardFocusChange
757 \li Set when the user changes focus with the keyboard
758 (see Qt::WA_KeyboardFocusChange)
759 \row
760 \li \c State_MouseOver
761 \li Set if the mouse cursor is over the widget
762 \row
763 \li \c State_Active
764 \li Set if the widget is a child of the active window.
765 \endtable
766
767 The other common members for widgets are:
768
769 \table 90%
770 \header
771 \li Member
772 \li Content
773 \row
774 \li rect
775 \li The bounding rectangle of the element to draw. This
776 is set to the widget bounding rectangle
777 (QWidget::rect()).
778 \row
779 \li direction
780 \li The layout direction; a value of the
781 Qt::LayoutDirection enum.
782 \row
783 \li palette
784 \li The QPalette to use when drawing the element. This
785 is set to the widgets palette (QWidget::palette()).
786 \row
787 \li fontMetrics
788 \li The QFontMetrics to use when drawing text on the
789 widget.
790 \endtable
791
792 The complex style options (classes that inherit
793 QStyleOptionComplex) used for complex style elements share two
794 variables: \l{QStyleOptionComplex::}{subControls} and
795 \l{QStyleOptionComplex::}{activeSubControls}. Both variables are
796 an OR'ed combination of QStyle::SubControl enum values. They
797 indicate which sub controls the complex control consists of and
798 which of these controls are currently active.
799
800 As mentioned, the style calculates the size of the widget's
801 contents, which the widgets calculate their size hints from. In
802 addition, complex controls also use the style to test which
803 sub-controls the mouse is over.
804
805 \section2 Widget Reference
806
807 Without further delay, we present the widget walkthrough; each
808 widget has its own sub-section.
809
810 \section3 Push Buttons
811
812 The style structure for push buttons is shown below. By doing a
813 top-down traversal of the tree, you get the sequence in which the
814 elements should be drawn.
815
816 \image javastyle/pushbutton.png
817 {Push button style tree and elements}
818
819 The layout of the buttons, with regard to element bounds, varies from
820 style to style. This makes it difficult to show conceptual images
821 of this. Also, elements may - even be intended to - have the same
822 bounds; the \c PE_PushButtonBevel, for instance, is used in
823 QCommonStyle to draw the elements that it contains:
824 \c PE_FrameDefaultButton, \c PE_FrameButtonBevel, and
825 \c PE_PanelButtonCommand, all of which have the same bounds in common
826 style. \c PE_PushButtonBevel is also responsible for drawing the menu
827 indicator (QCommonStyle draws \c PE_IndicatorArrowDown).
828
829 An image of a push button in the Java style that shows the bounding
830 rectangles of the elements is given below. Colors are used to
831 separate the bounding rectangles in the image; they do not fill
832 any other purpose. This is also true for similar images for the
833 other widgets.
834
835 \image javastyle/button.png {Button labeled with its elements}
836
837 The Java style, as well as all other styles implemented in Qt,
838 does not use \c PE_FrameButtonBevel. It is usual that a button
839 with a \c PE_DefaultFrame adjusts the \c PE_PanelButtonCommand's
840 rectangle by \c PM_ButtonDefaultIndicator. The \c CE_PushButtonLabel
841 is found by adjusting the rect by \c PM_DefaultFrameWidth.
842
843 We will now examine the style option for push
844 buttons - QStyleOptionButton. A table for the states that
845 QPushButton can set on the style option follows:
846
847 \table 90%
848 \header
849 \li State
850 \li State Set When
851 \row
852 \li \c State_Sunken
853 \li Button is down or menu is pressed shown
854 \row
855 \li \c State_On
856 \li Button is checked
857 \row
858 \li \c State_Raised
859 \li Button is not flat and not pressed down
860 \endtable
861
862 Other members of QStyleOptionButton are:
863
864 \table 90%
865 \header
866 \li Member
867 \li Content
868 \row
869 \li features
870 \li Flags of the QStyleOptionButton::ButtonFeatures enum,
871 which describes various button properties (see enum)
872 \row
873 \li icon
874 \li The buttons QIcon (if any)
875 \row
876 \li iconSize
877 \li The QSize of the icon
878 \row
879 \li text
880 \li a QString with the buttons text
881 \endtable
882
883 \section3 Check and Radio Buttons
884
885 The structures for radio and check buttons are identical.
886 We show the structure using QCheckBox element and pixel
887 metric names:
888
889 \image javastyle/checkbox.png
890 {Check and radio box style tree and elements}
891
892 QStyleOptionButton is used as the style option for both check
893 and radio buttons. We first give a table of the states that
894 can be set in the option:
895
896 \table 90%
897 \header
898 \li State
899 \li State Set When
900 \row
901 \li \c State_sunken
902 \li The box is pressed down
903 \row
904 \li \c State_NoChange
905 \li The box is partially checked (for tri-state
906 checkboxes.)
907 \row
908 \li \c State_On
909 \li The box is checked
910 \row
911 \li \c State_Off
912 \li The box is unchecked
913 \endtable
914
915 See \l{Push Buttons} for a table over other members in the
916 QStyleOptionButton class.
917
918 \section3 Tabs
919
920 In Qt, QTabBar uses the style to draw its tabs. Tabs exist either
921 in a QTabWidget, which contains a QTabBar, or as a separate bar.
922 If the bar is not part of a tab widget, it draws its own base.
923
924 QTabBar lays out the tabs, so the style does not have control over
925 tab placement. However, while laying out its tabs, the bar asks
926 the style for \c PM_TabBarTabHSpace and \c PM_TabBarTabVSpace, which is
927 extra width and height over the minimum size of the tab bar tab
928 label (icon and text). The style can also further influence the
929 tab size before it is laid out, as the tab bar asks for
930 \c CT_TabBarTab. The bounding rectangle of the bar is decided by the
931 tab widget when it is part of the widget (still considering
932 \c CT_TabBarTab).
933
934 The tab bar is responsible for drawing the buttons that appear on
935 the tab bar when all tabs do not fit. Their placement is not
936 controlled by the style, but the buttons are \l{QToolButton}s
937 and are therefore drawn by the style.
938
939 Here is the style structure for QTabWidget and QTabBar:
940
941 \image javastyle/tab.png
942 {Tab widget and tab bar style tree and elements}
943
944 The dotted lines indicate that the QTabWidget contains a tab bar,
945 but does not draw the tab bar itself. QTabBar only draws its base line
946 when not part of a tab widget, and it keeps two tool
947 buttons that scroll the bar when all tabs do not fit; see \l{Tool
948 Buttons} for their element tree. Also note that since the buttons
949 are children of the tab bar, they are drawn after the bar. The
950 tabs' bounding rectangles overlap the base by \c PM_TabBarBaseOverlap.
951
952 Here is a tab widget in the Java style:
953
954 \image javastyle/tabwidget.png {Tab widget labeled with its elements}
955
956 In the Java style, the tab bar shape and label have the same bounding
957 rectangle as \c CE_TabBarTab. Notice that the tabs overlap with the
958 tab widget frame. The base of the tab bar (if drawn) is the area where
959 the tabs and frame overlap.
960
961 The style option for tabs (QStyleOptionTab) contains the necessary
962 information for drawing tabs. The option contains the position of
963 the tab in the tab bar, the position of the selected tab, the
964 shape of the tab, the text, the icon, and the icon's size.
965
966 As the Java style tabs don't overlap, we also present an image of
967 a tab widget in the common style. Note that if you want the tabs
968 to overlap horizontally, you do that when drawing the tabs in
969 \c CE_TabBarTabShape; the tabs bounding rectangles will not be
970 altered by the tab bar. The tabs are drawn from left to right in a
971 north tab bar shape, top to bottom in an east tab bar shape, etc.
972 The selected tab is drawn last, so that it is easy to draw it over
973 the other tabs (if it is to be bigger).
974
975 \image javastyle/windowstabimage.png
976 {Tab bar labeled with its elements}
977
978 A table of the states a tab bar can set on its tabs follows:
979
980 \table 90%
981 \header
982 \li State
983 \li State Set When
984 \row
985 \li \c State_Sunken
986 \li The tab is pressed on with the mouse.
987 \row
988 \li \c State_Selected
989 \li If it is the current tab.
990 \row
991 \li \c State_HasFocus
992 \li The tab bar has focus and the tab is selected.
993 \endtable
994
995 Note that individual tabs may be disabled even if the tab bar
996 is not. The tab will be active if the tab bar is active.
997
998 Here follows a table of QStyleOptionTab's members:
999
1000 \table 90%
1001 \header
1002 \li Member
1003 \li Content
1004 \row
1005 \li cornerWidgets
1006 \li Flags of the CornerWidget enum, which indicate
1007 if and which corner widgets the tab bar has.
1008 \row
1009 \li icon
1010 \li The QIcon of the tab.
1011 \row
1012 \li iconSize
1013 \li The QSize of the icon.
1014 \row
1015 \li position
1016 \li A TabPosition enum value that indicates the tab's
1017 position on the bar relative to the other tabs.
1018 \row
1019 \li row
1020 \li Holds which row the tab is in.
1021 \row
1022 \li selectedPosition
1023 \li A value of the SelectedPosition enum that indicates
1024 whether the selected tab is adjacent to or is the
1025 tab.
1026 \row
1027 \li shape
1028 \li A value of the QTabBar::Shape enum indicating
1029 whether the tab has rounded or triangular corners
1030 and the orientation of the tab.
1031 \row
1032 \li text
1033 \li The tab text.
1034 \endtable
1035
1036 The frame for tab widgets use QStyleOptionTabWidgetFrame as
1037 style option. We list its members here. It does not have
1038 states set besides the common flags.
1039
1040 \table 90%
1041 \header
1042 \li Member
1043 \li content
1044 \row
1045 \li leftCornerWidgetSize
1046 \li The QSize of the left corner widget (if any).
1047 \row
1048 \li rightCornerWidgetSize
1049 \li The QSize of the right corner widget (if any).
1050 \row
1051 \li lineWidth
1052 \li Holds the line with for drawing the panel.
1053 \row
1054 \li midLineWith
1055 \li This value is currently always 0.
1056 \row
1057 \li shape
1058 \li The shape of the tabs on the tab bar.
1059 \row
1060 \li tabBarSize
1061 \li The QSize of the tab bar.
1062 \endtable
1063
1064 \section3 Scroll Bars
1065
1066 Here is the style structure for scrollbars:
1067
1068 \image javastyle/scrollbar.png
1069 {Scrollbar style tree and elements}
1070
1071 QScrollBar simply creates its style option and then draws
1072 \c CC_ScrollBar. Some styles draw the background of add page and sub
1073 page with \c PE_PanelButtonBevel, and also use indicator arrows to
1074 draw the arrows in the next and previous line indicators; we have
1075 not included these in the tree as their use is up to the
1076 individual style. The style's \c PM_MaximumDragDistance is the
1077 maximum distance in pixels the mouse can move from the bounds
1078 of the scroll bar and still move the handle.
1079
1080 Here is an image of a scrollbar in the Java style:
1081
1082 \image javastyle/scrollbarimage.png
1083 {Scrollbar labeled with its elements}
1084
1085 You may notice that the scrollbar is slightly different from
1086 Java's, as it has two line up indicators. We have done this to show
1087 that you can have two separate bounding rectangles for a
1088 single sub control. The scroll bar is an example of a widget that
1089 is entirely implemented by the Java style - QCommonStyle is not
1090 involved in the drawing.
1091
1092 We have a look at the different states a scroll bar can set on
1093 the style option:
1094
1095 \table 90%
1096 \header
1097 \li State
1098 \li State Set When
1099 \row
1100 \li \c State_Horizontal
1101 \li The scroll bar is horizontal.
1102 \endtable
1103
1104 The style option of QScrollBar is QStyleOptionSlider. Its
1105 members are listed in the following table. The option is used
1106 by all \l{QAbstractSlider}s; we only describe the members
1107 relevant for scroll bars here.
1108
1109 \table 90%
1110 \header
1111 \li Member
1112 \li Content
1113 \row
1114 \li maximum
1115 \li The maximum value of the scroll bar.
1116 \row
1117 \li minimum
1118 \li The minimum value of the scroll bar.
1119 \row
1120 \li notchTarget
1121 \li The number of pixels between notches.
1122 \row
1123 \li orientation
1124 \li A value of the Qt::Orientation enum that specifies
1125 whether the scroll bar is vertical or horizontal.
1126 \row
1127 \li pageStep
1128 \li The number by which to increase or decrease the slider's
1129 value (relative to the size of the slider and its value
1130 range) on page steps.
1131 \row
1132 \li singleStep
1133 \li The number by which to increase or decrease the slider's
1134 value on single (or line) steps.
1135 \row
1136 \li sliderValue
1137 \li The value of the slider.
1138 \row
1139 \li sliderPosition
1140 \li The position of the slider handle. This is the same
1141 as \c sliderValue if the scroll bar is
1142 QAbstractSlider::tracking. If not, the scroll
1143 bar does not update its value before the mouse
1144 releases the handle.
1145 \row
1146 \li upsideDown
1147 \li Holds the direction in which the scroll bar
1148 increases its value. This is used instead of
1149 QStyleOption::direction for all abstract sliders.
1150 \endtable
1151
1152 \section3 Sliders
1153
1154 When calculating the slider's size hint, \c PM_SliderThickness and
1155 \c PM_SliderLength are queried from the style. As with scroll bars,
1156 the QSlider only lets the user move the handle if the mouse is
1157 within \c PM_MaximumDragDistance from the slider bounds. When it
1158 draws itself, it creates the style option and calls \c
1159 drawComplexControl() with \c CC_Slider:
1160
1161 \image javastyle/slider.png {Slider style tree and elements}
1162
1163 We also show a picture of a slider in the Java style. We show
1164 the bounding rectangles of the sub elements, as all drawing is done
1165 in \c CC_Slider.
1166
1167 \image javastyle/sliderimage.png {Slider labeled with its elements}
1168
1169 QSlider uses QStyleOptionSlider as all \l{QAbstractSlider}s do. We
1170 present a table with the members that affect QSlider:
1171
1172 \table 90%
1173 \header
1174 \li Member
1175 \li Content
1176 \row
1177 \li maximum
1178 \li The maximum value of the slider.
1179 \row
1180 \li minimum
1181 \li The minimum value of the slider.
1182 \row
1183 \li notchTarget
1184 \li This is the number of pixels between each notch.
1185 \row
1186 \li orientation
1187 \li A Qt::Orientation enum value that indicates whether the
1188 slider is vertical or horizontal.
1189 \row
1190 \li pageStep
1191 \li The number by which to increase or decrease the slider's
1192 value on page steps.
1193 \row
1194 \li singleStep
1195 \li The number by which to increase or decrease the slider's
1196 value on single (or line) steps.
1197 \row
1198 \li sliderValue
1199 \li The value of the slider.
1200 \row
1201 \li sliderPosition
1202 \li The position of the slider given as a slider value.
1203 This will be equal to the \c sliderValue if the
1204 slider is \l{QAbstractSlider::}{tracking}; if
1205 not, the slider's value will not change until the handle is
1206 released with the mouse.
1207 \row
1208 \li upsideDown
1209 \li This member is used instead of QStyleOption::direction
1210 for all abstract sliders.
1211 \endtable
1212
1213 You should note that the slider does not use direction for
1214 reverse layouts; it uses \c upsideDown.
1215
1216 \section3 Spin Boxes
1217
1218 When QSpinBox paints itself, it creates a QStyleOptionSpinBox and
1219 asks the style to draw \c CC_SpinBox. The edit field is a line
1220 edit that is a child of the spin box. The dimensions of the
1221 field are calculated by the style with \c SC_SpinBoxEditField.
1222
1223 Here follows the style tree for spin boxes. It is not
1224 required that a style uses the button panel primitive to paint
1225 the indicator backgrounds. You can see an image below the tree
1226 showing the sub elements in QSpinBox in the Java style.
1227
1228 \image javastyle/spinbox.png {Spin box style tree and elements}
1229
1230 \image javastyle/spinboximage.png {Spin box labeled with its elements}
1231
1232 The QStyleOptionSpinBox, which is the style option for spin
1233 boxes. It can set the following states on the spin box:
1234
1235 \table 90%
1236 \header
1237 \li State
1238 \li State Set When
1239 \row
1240 \li \c State_Sunken
1241 \li Is set if one of the sub controls \c CC_SpinUp or
1242 \c CC_SpinDown is pressed on with the mouse.
1243 \endtable
1244
1245 The rest of the members in the spin box style options are:
1246
1247 \table 90%
1248 \header
1249 \li Property
1250 \li Function
1251 \row
1252 \li frame
1253 \li Boolean that is \c true if the spin box is to draw a
1254 frame.
1255 \row
1256 \li buttonSymbols
1257 \li Value of the ButtonSymbols enum that decides the
1258 symbol on the up/down buttons.
1259 \row
1260 \li stepEnabled
1261 \li A value of the StepEnabled enum, indicating which of the
1262 spin box buttons are pressed down.
1263 \endtable
1264
1265 \section3 Title Bar
1266
1267 The title bar complex control, \c CC_TitleBar, is used to draw
1268 the title bars of internal windows in QMdiArea. It typically
1269 consists of a window title, and close, minimize, system menu, and
1270 maximize buttons. Some styles also provide buttons for shading
1271 the window, as well as a button for context sensitive help.
1272
1273 The bar is drawn in \c CC_TitleBar without using any sub elements.
1274 How the individual styles draw their buttons is up to them, but
1275 there are standard pixmaps for the buttons that the style should
1276 provide.
1277
1278 \image javastyle/titlebar.png
1279 {Title bar style tree and elements}
1280
1281 In an image over a title bar in the Java style, we show the
1282 bounding rectangles of the sub elements supported by the Java style
1283 (all of which are drawn with standard pixmaps). It is usual to
1284 draw the button backgrounds using \c PE_PanelButtonTool, but it's not
1285 mandatory.
1286
1287 \image javastyle/titlebarimage.png
1288 {Title bar labeled with its elements}
1289
1290 The style option for title bars is QStyleOptionTitleBar. Its
1291 members are:
1292
1293 \table 90%
1294 \header
1295 \li Member
1296 \li Content
1297 \row
1298 \li icon
1299 \li The title bar's icon.
1300 \row
1301 \li text
1302 \li The text for the title bar's label.
1303 \row
1304 \li windowFlags
1305 \li Flags of the Qt::WindowFlag enum. The window flags
1306 used by QMdiArea for window management.
1307 \row
1308 \li titleBarState
1309 \li This is the QWidget::windowState() of the window
1310 that contains the title bar.
1311 \endtable
1312
1313 \section3 Combo Box
1314
1315 A QComboBox uses the style to draw the button and label of
1316 non-editable boxes with \c CC_ComboBox and \c CE_ComboBoxLabel.
1317
1318 The list that pops up when the user clicks on the combo box is
1319 drawn by a \l{Delegate Classes}{delegate}, which we do not cover
1320 in this overview. You can, however, use the style to control the
1321 list's size and position with the sub element
1322 \c SC_ComboBoxListBoxPopup. The style also decides where the edit
1323 field for editable boxes should be with \c SC_ComboBoxEditField; the
1324 field itself is a QLineEdit that is a child of the combo box.
1325
1326 \image javastyle/combobox.png
1327 {Combo box style tree and elements}
1328
1329 We show an image over a Java style combo box in which we have
1330 outlined its sub elements and sub element rectangles:
1331
1332 \image javastyle/comboboximage.png
1333 {Combo box labeled with its elements}
1334
1335 Java combo boxes do not use the focus rect; it changes its
1336 background color when it has focus. The \c SC_ComboBoxEdit field is
1337 used both by QComboBox to calculate the size of the edit field and
1338 the style for calculating the size of the combo box label.
1339
1340 The style option for combo boxes is QStyleOptionComboBox. It
1341 can set the following states:
1342
1343 \table 90%
1344 \header
1345 \li State
1346 \li Set When
1347 \row
1348 \li \c State_Selected
1349 \li The box is not editable and has focus.
1350 \row
1351 \li \c State_Sunken
1352 \li \c SC_ComboBoxArrow is active.
1353 \row
1354 \li \c State_on
1355 \li The container (list) of the box is visible.
1356 \endtable
1357
1358 The style options other members are:
1359
1360 \table
1361 \header
1362 \li Member
1363 \li Content
1364 \row
1365 \li currentIcon
1366 \li The icon of the current (selected) item of the
1367 combo box.
1368 \row
1369 \li currentText
1370 \li The text of the current item in the box.
1371 \row
1372 \li editable
1373 \li Holds whether the combo box is editable or not.
1374 \row
1375 \li frame
1376 \li Holds whether the combo box has a frame or not.
1377 \row
1378 \li iconSize
1379 \li The size of the current items icon.
1380 \row
1381 \li popupRect
1382 \li The bounding rectangle of the combo box's popup
1383 list.
1384 \endtable
1385
1386 \section3 Group Boxes
1387
1388 When calculating the size hint, QGroupBox fetches three pixel
1389 metrics from the style: \c PM_IndicatorWidth,
1390 \c PM_CheckBoxLabelSpacing, and \c PM_IndicatorHeight. QGroupBox has
1391 the following style element tree:
1392
1393 \image javastyle/groupbox.png
1394 {Group box style tree and elements}
1395
1396 Qt does not impose restrictions on how the check box is drawn; the
1397 Java style draws it with \c CE_IndicatorCheckBox. See \l{Check and
1398 Radio Buttons} for the complete tree.
1399
1400 We also give an image of the widget with the sub controls and
1401 sub control rectangles drawn:
1402
1403 \image javastyle/groupboximage.png
1404 {Group box labeled with its elements}
1405
1406 The style option for group boxes is QStyleOptionGroupBox. The
1407 following states can be set on it:
1408
1409 \table 90%
1410 \header
1411 \li State
1412 \li Set When
1413 \row
1414 \li \c State_On
1415 \li The check box is checked.
1416 \row
1417 \li \c State_Sunken
1418 \li The check box is pressed down.
1419 \row
1420 \li \c State_Off
1421 \li The check box is unchecked (or there is no check box).
1422 \endtable
1423
1424 The remaining members of QStyleOptionGroupBox are:
1425
1426 \table
1427 \header
1428 \li Member
1429 \li Content
1430 \row
1431 \li features
1432 \li Flags of the QStyleOptionFrame::FrameFeatures
1433 enum describing the frame of the group box.
1434 \row
1435 \li lineWidth
1436 \li The line width with which to draw the panel. This
1437 is always 1.
1438 \row
1439 \li text
1440 \li The text of the group box.
1441 \row
1442 \li textAlignment
1443 \li The alignment of the group box title.
1444 \row
1445 \li textColor
1446 \li The QColor of the text.
1447 \endtable
1448
1449 \section3 Splitters
1450
1451 As the structure of splitters are simple and do not contain any
1452 sub elements, we do not include any images of splitters. \c CE_Splitter
1453 does not use any other elements or metrics.
1454
1455 For its style option, the splitter uses the base class QStyleOption.
1456 It can set the following state flags on it:
1457
1458 \table 90%
1459 \header
1460 \li State
1461 \li Set When
1462 \row
1463 \li \c State_Horizontal
1464 \li Set if it is a horizontal splitter.
1465 \endtable
1466
1467 QSplitter does not use \l{QStyleOption::}{initFrom()} to set up its
1468 option; it sets the \c State_MouseOver and \c State_Disabled flags
1469 itself.
1470
1471 \section3 Progress Bar
1472
1473 The \c CE_ProgressBar element is used by QProgressBar, and it is the
1474 only element used by this widget. We start with the style structure:
1475
1476 \image javastyle/progressbar.png
1477 {Progress bar style tree and elements}
1478
1479 Here is a progress bar in the common style (the Java style
1480 bounding rectangles are equal):
1481
1482 \image javastyle/progressbarimage.png
1483 {Progress bar labeled with its elements}
1484
1485 The style option for QProgressBar is QStyleOptionProgressBar.
1486 The bar does not set any state flags, but the other members of the
1487 option are:
1488
1489 \table 90%
1490 \header
1491 \li Member
1492 \li Content
1493 \row
1494 \li minimum
1495 \li The minimum value of the bar.
1496 \row
1497 \li maximum
1498 \li The maximum value of the bar.
1499 \row
1500 \li progress
1501 \li The current value of the bar.
1502 \row
1503 \li textAlignment
1504 \li How the text is aligned in the label.
1505 \row
1506 \li textVisible
1507 \li Whether the label is drawn.
1508 \row
1509 \li text
1510 \li The label text.
1511 \row
1512 \li orientation
1513 \li Progress bars can be vertical or horizontal.
1514 \row
1515 \li invertedAppearance
1516 \li The progress is inverted (i.e., right to left in a
1517 horizontal bar).
1518 \row
1519 \li bottomToTop
1520 \li Boolean, that, if \c true, turns the label of vertical
1521 progress bars 90 degrees.
1522 \endtable
1523
1524 \section3 Tool Buttons
1525
1526 Tool buttons exist either independently or as part of tool bars.
1527 They are drawn equally either way. The QToolButton draws only one
1528 style element: \c CC_ToolButton.
1529
1530 Below is a tree of the widget's style structure:
1531
1532 \image javastyle/toolbutton.png
1533 {Tool button style tree and elements}
1534
1535 Note that \c PE_FrameButtonTool and \c PE_IndicatorArrowDown are
1536 included in the tree as the Java style draws them, but they can
1537 safely be omitted if you prefer it. The structure may also be
1538 different. QCommonStyle, for instance, draws both
1539 \c PE_IndicatorButtonDropDown and \c PE_IndicatorArrowDown in
1540 \c CE_ToolButton.
1541
1542 We also have an image of a tool button where we have outlined
1543 the sub element bounding rectangles and sub controls.
1544
1545 \image javastyle/toolbuttonimage.png
1546 {Tool button labeled with its elements}
1547
1548 Here is the states table for tool buttons:
1549
1550 \table 90%
1551 \header
1552 \li State
1553 \li Set When
1554 \row
1555 \li \c State_AutoRise
1556 \li The tool button has the autoRise property set.
1557 \row
1558 \li \c State_Raised
1559 \li The button is not sunken (i.e., by being checked or
1560 pressed on with the mouse).
1561 \row
1562 \li \c State_Sunken
1563 \li The button is down.
1564 \row
1565 \li \c State_On
1566 \li The button is checkable and checked.
1567 \endtable
1568
1569 QStyleOptionToolButton also contains the following members:
1570
1571 \table
1572 \header
1573 \li Member
1574 \li Content
1575 \row
1576 \li arrowType
1577 \li A Qt::ArrowType enum value, which contains the
1578 direction of the buttons arrow (if an arrow is to
1579 be used in place of an icon).
1580 \row
1581 \li features
1582 \li Flags of the QStyleOptionToolButton::ButtonFeature
1583 enum describing if the button has an arrow, a menu,
1584 and/or has a popup-delay.
1585 \row
1586 \li font
1587 \li The QFont of the buttons label.
1588 \row
1589 \li icon
1590 \li The QIcon of the tool button.
1591 \row
1592 \li iconSize
1593 \li The icon size of the button's icon.
1594 \row
1595 \li pos
1596 \li The position of the button, as given by
1597 QWidget::pos()
1598 \row
1599 \li text
1600 \li The text of the button.
1601 \row
1602 \li toolButtonStyle
1603 \li A Qt::ToolButtonStyle enum value which decides
1604 whether the button shows the icon, the text, or both.
1605 \endtable
1606
1607 \section3 Toolbars
1608
1609 Toolbars are part of the \l{QMainWindow}{main window framework},
1610 and cooperate with the QMainWindow to which they belong while it
1611 builds its style option. A main window has 4 areas that toolbars
1612 can be placed in. They are positioned next to the four sides of
1613 the window (i.e., north, south, east and west). Within each area
1614 there can be more than one line of toolbars; a line consists of
1615 toolbars with equal orientation (vertical or horizontal) placed
1616 next to each other.
1617
1618 \l{QToolBar}{Toolbars} in Qt consist of three elements:
1619 \c CE_ToolBar, \c PE_IndicatorToolBarHandle, and
1620 \c PE_IndicatorToolBarSeparator. It is QMainWindowLayout that
1621 calculates the bounding rectangles (i.e., position and size of the
1622 toolbars and their contents. The main window also uses the \c
1623 sizeHint() of the items in the toolbars when calculating the size
1624 of the bars.
1625
1626 Here is the element tree for QToolBar:
1627
1628 \image javastyle/toolbar.png
1629 {Tool bar style tree and elements}
1630
1631 The dotted lines indicate that the QToolBar keeps an instance of
1632 QToolBarLayout and that QToolBarSeparators are kept by
1633 QToolBarLayout. When the toolbar is floating (i.e., has its own
1634 window) the \c PE_FrameMenu element is drawn, else QToolBar draws
1635 \c CE_ToolBar.
1636
1637 Here is an image of a toolbar in the Java style:
1638
1639 \image javastyle/toolbarimage.png
1640 {Tool bar labeled with its elements}
1641
1642 QToolBarSaparator uses QStyleOption for its style option. It
1643 sets the \c State_Horizontal flag if the toolbar it lives in is
1644 horizontal. Other than that, they use \l{QStyleOption::}{initFrom()}.
1645
1646 The style option for QToolBar is QStyleOptionToolBar. The only
1647 state flag set (besides the common flags) is \c State_Horizontal
1648 if the bar is horizontal (i.e., in the north or south toolbar area).
1649 The member variables of the style option are:
1650
1651 \table 90%
1652 \header
1653 \li Member
1654 \li Content
1655 \row
1656 \li features
1657 \li Holds whether the bar is movable in a value of the
1658 ToolBarFeature, which is either Movable or None.
1659 \row
1660 \li lineWidth
1661 \li The width of the tool bar frame.
1662 \row
1663 \li midLineWidth
1664 \li This variable is currently not used and is always 0.
1665 \row
1666 \li positionOfLine
1667 \li The position of the toolbar line within the toolbar
1668 area to which it belongs.
1669 \row
1670 \li positionWithinLine
1671 \li The position of the toolbar within the toolbar line.
1672 \row
1673 \li toolBarArea
1674 \li The toolbar area in which the toolbar lives.
1675 \endtable
1676
1677 \section3 Menus
1678
1679 Menus in Qt are implemented in QMenu. The QMenu keeps a list of
1680 actions, which it draws as menu items. When QMenu receives paint
1681 events, it calculates the size of each menu item and draws them
1682 individually with \c CE_MenuItem. Menu items do not have a separate
1683 element for their label (contents), so all drawing is done in
1684 \c CE_MenuItem. The menu also draws the frame of the menu with
1685 \c PE_FrameMenu. It also draws \c CE_MenuScroller if the style supports
1686 scrolling. \c CE_MenuTearOff is drawn if the menu is too large for its
1687 bounding rectangle.
1688
1689 In the style structure tree, we also include QMenu as it also does
1690 styling related work. The bounding rectangles of menu items are
1691 calculated for the menu's size hint and when the menu is displayed
1692 or resized.
1693
1694 \image javastyle/menu.png {Menu style tree and elements}
1695
1696 The \c CE_MenuScroller and \c CE_MenuTearOff elements are handled by
1697 QCommonStyle and are not shown unless the menu is too large to fit
1698 on the screen. \c PE_FrameMenu is only drawn for pop-up menus.
1699
1700 QMenu calculates rectangles based on its actions and calls
1701 \c CE_MenuItem and \c CE_MenuScroller if the style supports that.
1702
1703 It is also usual to use \c PE_IndicatorCheckBox (instead of using
1704 \c PE_IndicatorMenuCheckMark) and \c PE_IndicatorRadioButton for drawing
1705 checkable menu items; we have not included them in the style tree
1706 as this is optional and varies from style to style.
1707
1708 \image javastyle/menuimage.png
1709 {Menu labeled with its elements}
1710
1711 The style option for menu items is QStyleOptionMenuItem. The
1712 following tables describe its state flags and other members.
1713
1714 \table 90%
1715 \header
1716 \li State
1717 \li Set When
1718 \row
1719 \li \c State_Selected
1720 \li The mouse is over the action and the action is not
1721 a separator.
1722 \row
1723 \li \c State_Sunken
1724 \li The mouse is pressed down on the menu item.
1725 \row
1726 \li \c State_DownArrow
1727 \li Set if the menu item is a menu scroller and it scrolls
1728 the menu downwards.
1729 \endtable
1730
1731 \table 90%
1732 \header
1733 \li Member
1734 \li Content
1735 \row
1736 \li checkType
1737 \li A value of the \l{QStyleOptionMenuItem::}{CheckType} enum,
1738 which is either NotCheckable, Exclusive, or
1739 NonExclusive.
1740 \row
1741 \li checked
1742 \li Boolean that is \c true if the menu item is checked.
1743 \row
1744 \li font
1745 \li The QFont to use for the menu item's text.
1746 \row
1747 \li icon
1748 \li The QIcon of the menu item.
1749 \row
1750 \li maxIconWidth
1751 \li The maximum width allowed for the icon.
1752 \row
1753 \li menuHasCheckableItems
1754 \li Boolean which is \c true if at least one item in the
1755 menu is checkable.
1756 \row
1757 \li menuItemType
1758 \li The type of the menu item. This a value of the
1759 \l{QStyleOptionMenuItem::}{MenuItemType}.
1760 \row
1761 \li menuRect
1762 \li The bounding rectangle for the QMenu that the menu
1763 item lives in.
1764 \row
1765 \li tabWidth
1766 \li This is the distance between the text of the menu
1767 item and the shortcut.
1768 \row
1769 \li text
1770 \li The text of the menu item.
1771 \endtable
1772
1773 The setup of the style option for \c CE_MenuTearOff and
1774 \c CE_MenuScroller also uses QStyleOptionMenuItem; they only set the
1775 \c menuRect variable in addition to the common settings with
1776 QStyleOption's \l{QStyleOption::}{initFrom()}.
1777
1778 \section3 Menu Bar
1779
1780 QMenuBar uses the style to draw each menu bar item and the empty
1781 area of the menu bar. The pull-down menus themselves are
1782 \l{QMenu}s (see \l{Menus}). The style element tree for the menu
1783 bar follows:
1784
1785 \image javastyle/menubar.png
1786 {Menu bar style tree and elements}
1787
1788 The panel and empty area are drawn after the menu items. The
1789 QPainter that the QMenuBar sends to the style has the bounding
1790 rectangles of the items clipped out (i.e., clip region), so you
1791 don't need to worry about drawing over the items. The pixel
1792 metrics in QMenuBar are used when the bounding rectangles of the
1793 menu bar items are calculated.
1794
1795 \image javastyle/menubarimage.png
1796 {Menu bar labeled with its elements}
1797
1798 QStyleOptionMenuItem is used for menu bar items. The members that
1799 are used by QMenuBar are described in the following table:
1800
1801 \table
1802 \header
1803 \li Member
1804 \li Content
1805 \row
1806 \li menuRect
1807 \li The bounding rectangle of the entire menu bar to
1808 which the item belongs.
1809 \row
1810 \li text
1811 \li The text of the item.
1812 \row
1813 \li icon
1814 \li The icon of the menu item (it is not common that
1815 styles draw this icon).
1816 \endtable
1817
1818 QStyleOptionMenuItem is also used for drawing \c CE_EmptyMenuBarArea.
1819
1820 QStyleOptionFrame is used for drawing the panel frame. The
1821 \l{QStyleOptionFrame::}{lineWidth} is set to \c PM_MenuBarPanelWidth.
1822 The \l{QStyleOptionFrame::}{midLineWidth} is currently always set
1823 to 0.
1824
1825 \section3 Item View Headers
1826
1827 It is the style that draws the headers of Qt's item views. The
1828 item views keep the dimensions on individual sections. Also
1829 note that the delegates may use the style to paint decorations
1830 and frames around items. QItemDelegate, for instance, draws
1831 \c PE_FrameFocusRect and \c PE_IndicatorItemViewItemCheck.
1832
1833 \image javastyle/header.png
1834 {Header style tree and elements}
1835
1836 Here is a QTableWidget showing the bounding rects of a Java
1837 header:
1838
1839 \image javastyle/headerimage.png
1840 {Header labeled with its elements}
1841
1842 The QHeaderView uses \c CT_HeaderSection, \c PM_HeaderMargin and
1843 \c PM_HeaderGripMargin for size and hit test calculations. The
1844 \c PM_HeaderMarkSize is currently not used by Qt. QTableView draws
1845 the button in the top-left corner (i.e., the area where the
1846 vertical and horizontal headers intersect) as a \c CE_Header.
1847
1848 The style option for header views is QStyleOptionHeader. The view
1849 paints one header section at a time, so the data is for the
1850 section being drawn. Its contents are:
1851
1852 \table 90%
1853 \header
1854 \li Member
1855 \li Content
1856 \row
1857 \li icon
1858 \li The icon of the header (for section that is being drawn).
1859 \row
1860 \li iconAlignment
1861 \li The alignment (Qt::Alignment) of the icon in the header.
1862 \row
1863 \li orientation
1864 \li A Qt::Orientation value deciding whether the header
1865 is the horizontal header above the view or the
1866 vertical header on the left.
1867 \row
1868 \li position
1869 \li A QStyleOptionHeader::SectionPosition value
1870 giving the header section's position relative to
1871 the other sections.
1872 \row
1873 \li section
1874 \li Holds the section that is being drawn.
1875 \row
1876 \li selectedPosition
1877 \li A QStyleOptionHeader::SelectedPosition value giving
1878 the selected section's position relative to the
1879 section that is being painted.
1880 \row
1881 \li sortIndicator
1882 \li A QStyleOptionHeader::SortIndicator value that
1883 describes the direction in which the section's sort
1884 indicator should be drawn.
1885 \row
1886 \li text
1887 \li The text of the currently drawn section.
1888 \row
1889 \li textAlignment
1890 \li The Qt::Alignment of the text within the header section.
1891 \endtable
1892
1893 \section3 Tree Branch Indicators
1894
1895 The branch indicators in a tree view are drawn by the style with
1896 \c PE_IndicatorBranch. We think of indicators here as the indicators
1897 that describe the relationship of the nodes in the tree. The
1898 generic QStyleOption is sent to the style for drawing these
1899 elements. The various branch types are described by states. Since
1900 there is no specific style option, we simply present the states
1901 table:
1902
1903 \table 90%
1904 \header
1905 \li State
1906 \li Set When
1907 \row
1908 \li \c State_Sibling
1909 \li The node in the tree has a sibling (i.e., there is
1910 another node in the same column).
1911 \row
1912 \li \c State_Item
1913 \li This branch indicator has an item.
1914 \row
1915 \li \c State_Children
1916 \li The branch has children (i.e., a new sub-tree can
1917 be opened at the branch).
1918 \row
1919 \li \c State_Open
1920 \li The branch indicator has an opened sub-tree.
1921 \endtable
1922
1923 The tree view (and tree widget) use the style to draw the branches
1924 (nodes) of the tree.
1925
1926 QStyleOption is used as the style for \c PE_IndicatorBranch has state
1927 flags set depending on what type of branch it is.
1928
1929 Since there is no tree structure for branch indicators, we only
1930 present an image of a tree in the Java style. Each state is marked
1931 in the image with a rectangle in a specific color (i.e., the
1932 rectangles are not bounding rectangles). All combinations of
1933 states you must be aware of are represented in the image.
1934
1935 \image javastyle/branchindicatorimage.png
1936 {Branch indicator style structure and drawing states}
1937
1938 \section3 Tool Boxes
1939
1940 \c PM_SmallIconSize for sizeHints.
1941
1942 QToolBox is a container that keeps a collection of widgets. It has
1943 one tab for each widget and displays one of them at a time. The
1944 tool box lays the components it displays (the tool box buttons
1945 and selected widget) in a QVBoxLayout. The style tree for tool
1946 boxes looks like this:
1947
1948 \image javastyle/toolbox.png
1949 {Tool box style tree and elements}
1950
1951 We show an image of a tool box in the Plastique style:
1952
1953 \image javastyle/toolboximage.png
1954 {Tool box labeled with its elements}
1955
1956 All elements have the same bounding rectangles in the
1957 Plastique style as well as the other built-in Qt styles.
1958
1959 The style option for tool boxes is QStyleOptionToolBox. It
1960 contains the text and icon of the tool box contents. The only
1961 state set by QToolBox is \c State_Sunken, which is set when the user
1962 presses a tab down with the mouse. The rest of the
1963 QStyleOptionToolBox members are:
1964
1965 \table 90%
1966 \header
1967 \li Member
1968 \li Content
1969 \row
1970 \li icon
1971 \li The icon on the toolbox tab.
1972 \row
1973 \li text
1974 \li The text on the toolbox tab.
1975 \endtable
1976
1977 \section3 Size Grip
1978
1979 The size grip calculates its size hint with \c CT_SizeGrip. The pixel
1980 metric \c PM_SizeGripSize is currently unused by Qt. The element tree
1981 for an image in the Plastique style of QSizeGrip follows:
1982
1983 \image javastyle/sizegrip.png {Size grip style tree and elements}
1984
1985 \image javastyle/sizegripimage.png {Size grip labeled with its elements}
1986
1987 We show the size grip in \l{QMainWindow}'s bottom right
1988 corner.
1989
1990 The size grip style option, QStyleOptionSizeGrip, has one
1991 member besides the common members from QStyleOption:
1992
1993 \table 90%
1994 \header
1995 \li Member
1996 \li Content
1997 \row
1998 \li corner
1999 \li A Qt::Corner value that describes which corner in a
2000 window (or equivalent) the grip is located.
2001 \endtable
2002
2003 \section3 Rubber Band
2004
2005 The \l{QRubberBand}'s style tree consists of two nodes.
2006
2007 \image javastyle/rubberband.png {Rubber band style tree and its elements}
2008
2009 We present an image of a Java style window being moved in a
2010 QMdiArea with a rubber band:
2011
2012 \image javastyle/rubberbandimage.png
2013 {Rubber band labeled with its elements}
2014
2015 The style option for rubber bands is QStyleOptionRubberBand.
2016 Its members are:
2017
2018 \table
2019 \header
2020 \li Member
2021 \li Content
2022 \row
2023 \li opaque
2024 \li Boolean that is \c true if the rubber band must be
2025 drawn in an opaque style (i.e., color).
2026 \row
2027 \li shape
2028 \li A QRubberBand::Shape enum value that holds the
2029 shape of the band (which is either a rectangle or a
2030 line).
2031 \endtable
2032
2033 \section3 Dock Widgets
2034
2035 When the dock widget lays out its contents it asks the style for
2036 these pixel metrics: \c PM_DockWidgetSeparatorExtent,
2037 \c PM_DockWidgetTitleBarButtonMargin, \c PM_DockWidgetFrameWidth, and
2038 \c PM_DockWidgetTitleMargin. It also calculates the bounding
2039 rectangles of the float and close buttons with
2040 \c SE_DockWidgetCloseButton and \c SE_DockWidgetFloatButton.
2041
2042 \image javastyle/dockwidget.png {Dock widget style tree and elements}
2043
2044 The dotted lines indicate that the sender keeps instances of the
2045 recipient of the arrow (i.e., it is not a style element to draw).
2046 The dock widget only draws \c PE_frameDockWidget when it is detached
2047 from its main window (i.e., it is a top level window). If it is
2048 docked it draws the indicator dock widget resize handle. We show a
2049 dock widget in both docked and floating state in the plastique
2050 style:
2051
2052 \image javastyle/dockwidgetimage.png {Dock widget labeled with its elements}
2053
2054 The style option is QStyleOptionDockWidget:
2055
2056 \table 90%
2057 \header
2058 \li Member
2059 \li Content
2060 \row
2061 \li closeable
2062 \li Boolean that holds whether the dock window can be
2063 closed.
2064 \row
2065 \li floatable
2066 \li Boolean that holds whether the dock window can
2067 float (i.e., detach from the main window in which
2068 it lives).
2069 \row
2070 \li movable
2071 \li Boolean that holds whether the window is movable
2072 (i.e., can move to other dock widget areas).
2073 \row
2074 \li title
2075 \li The title text of the dock window.
2076 \endtable
2077
2078 For the buttons, QStyleOptionButton is used (see \l{Tool Buttons}
2079 for content description). The dock widget resize handle has a
2080 plain QStyleOption.
2081*/