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. Notice that keypad
537 navigation must be enabled in Qt for the \c State_HasEditFocus to
538 be included; it is not included by default.
539
540 In addition to setting state flags the QStyleOption contains
541 other information about the widget: \c direction is the layout
542 direction of the layout, \c rect is the bounding rectangle of the
543 widget (the area in which to draw), \c palette is the QPalette
544 that should be used for drawing the widget, and \c fontMetrics is
545 the metrics of the font that is used by the widget.
546
547 We give an image of a checkbox and the style option to match
548 it.
549
550 \image javastyle/checkboxexample.png {Checkbox using the Java style}
551
552 The above checkbox will have the following state flags in its
553 style option:
554
555 \table 90%
556 \header
557 \li State flag
558 \li Set
559 \row
560 \li \c State_Sunken
561 \li Yes
562 \row
563 \li \c State_NoChange
564 \li No
565 \row
566 \li \c State_On
567 \li Yes
568 \row
569 \li \c State_Off
570 \li No
571 \row
572 \li \c State_MouseOver
573 \li Yes
574 \row
575 \li \c State_Enabled
576 \li Yes
577 \row
578 \li \c State_HasFocus
579 \li Yes
580 \row
581 \li \c State_KeyboardFocusChange
582 \li No
583 \row
584 \li \c State_Active
585 \li Yes
586 \endtable
587
588 The QCheckBox paints itself in QWidget::paintEvent() with
589 style option \c opt and QStylePainter \c p. The QStylePainter
590 class is a convenience class to draw style elements. Most
591 notably, it wraps the methods in QStyle used for painting. The
592 QCheckBox draws itself as follows:
593
594 \snippet code/doc_src_styles.cpp 2
595
596 QCommonStyle handles the CE_CheckBox element. The QCheckBox
597 has two sub elements: SE_CheckBoxIndicator (the checked indicator)
598 and SE_CheckBoxContents (the contents, which are used for the
599 checkbox label). QCommonStyle also implements these sub element
600 bounding rectangles. Next, we'll have a look at the QCommonStyle code:
601
602 \snippet code/doc_src_styles.cpp 3
603
604 As can be seen from the code extract, the common style gets
605 the bounding rectangles of the two sub elements of
606 CE_CheckBox, and then draws them. If the checkbox has focus,
607 the focus frame is also drawn.
608
609 The Java style draws CE_CheckBoxIndicator, while QCommonStyle
610 handles CE_CheckboxLabel. We will examine each implementation and
611 start with CE_CheckBoxLabel:
612
613 \snippet code/doc_src_styles.cpp 4
614
615 \l{QStyle::}{visualAlignment()} adjusts the alignment of text
616 according to the layout direction. We then draw an icon if it
617 exists, and adjust the space left for the text.
618 \l{QStyle::}{drawItemText()} draws the text, taking alignment,
619 layout direction, and the mnemonic into account. It also uses the
620 palette to draw the text in the right color.
621
622 The drawing of labels often gets somewhat involved. Luckily, it
623 can usually be handled by the base class. The Java style
624 implements its own push button label, since Java centers button
625 contents also when the button has an icon. You can examine that
626 implementation if you need an example of reimplementing label
627 drawing.
628
629 We'll now take a look at the Java implementation
630 of CE_CheckBoxIndicator in \c drawControl():
631
632 \snippet javastyle.cpp 0
633
634 We first save the state of the painter. This is not always
635 necessary, but in this case the QCommonStyle needs the painter in
636 the same state as it was when PE_IndicatorCheckBox was called (We
637 could also set the state with function calls, of course). We then
638 use \c drawButtonBackground() to draw the background of the check
639 box indicator. This is a helper function that draws the background
640 and also the frame of push buttons and check boxes. We take a look
641 at that function below. We then check if the mouse is hovering
642 over the checkbox. If it is, we draw the frame that Java checkboxes
643 have when the box is not pressed down and the mouse is over it.
644 You may note that Java does not handle tri-state boxes, so we have
645 not implemented it.
646
647 Here we use a PNG image for our indicator. We could also check
648 if the widget is disabled. We would then have to use
649 another image with the indicator in the disabled color.
650
651 \snippet javastyle.cpp 1
652
653 We have seen how check boxes are styled in the Java style from the
654 time the widget gets a paint request to the time the style is
655 finished painting. To learn in detail how each widget is painted,
656 you need to go through the code step-by-step as we have done here.
657 However, it is usually enough to know which style elements the
658 widgets draw. The widget builds a style option and calls on the
659 style one or more times to draw the style elements of which it
660 consists. Usually, it is also sufficient to know the states a widget
661 can be in and the other contents of the style option, i.e., what we
662 list in the next section.
663
664 \section1 Widget Walkthrough
665
666 In this section, we will examine how most of Qt's widgets are
667 styled. Hopefully, this will save you some time and effort while
668 developing your own styles and widgets. You will not find
669 information here that is not attainable elsewhere (i.e., by
670 examining the source code or the class descriptions for the style
671 related classes).
672
673 We mostly use Java style widgets as examples. The Java style does not
674 draw every element in the element trees. This is because they are
675 not visible for that widget in the Java style. We still make sure
676 that all elements are implemented in a way that conforms with the
677 Java style, as custom widgets might need them (this does not
678 exclude leaving implementations to QCommonStyle though).
679
680 The following is given for each widget:
681
682 \list
683 \li A table with the members (variables, etc.) of its style option.
684 \li A table of the state flags (QStyle::StateFlag) that
685 can be set on the widget and when the states are set.
686 \li Its element tree (see section \l{The Style Elements}).
687 \li An image of the widget in which the elements are outlined.
688 \omit This is not written yet - probably never will be
689 either
690 \li A list of style hints that should be checked for the
691 widget.
692 \li A list of standard pixmaps that could be used by the
693 elements.
694 \endomit
695 \endlist
696
697 The element tree contains the primitive, control, and complex
698 style elements. By doing a top-down traversal of the element tree,
699 you get the sequence in which the elements should be drawn. In the
700 nodes, we have written the sub element rectangles, sub control
701 elements, and pixel metrics that should be considered when drawing
702 the element of the node.
703
704 Our approach on styling centers on the drawing of the widgets. The
705 calculations of sub elements rectangles, sub controls, and pixel
706 metrics used \b during drawing is only listed as contents in
707 the element trees. Note that there are rectangles and pixel
708 metrics that are only used by widgets. This leaves these
709 calculations untreated in the walkthrough. For instance, the
710 \l{QStyle::}{subControlRect()} and
711 \l{QStyle::}{sizeFromContents()} functions often call
712 \l{QStyle::}{subElementRect()} to calculate their bounding
713 rectangles. We could draw trees for this as well. However, how
714 these calculations are done is completely up to the individual
715 styles, and they do not have to follow a specific structure (Qt
716 does not impose a specific structure). You should still make sure
717 that you use the appropriate pixel metrics, though. To limit the
718 size of the document, we have therefore chosen not to include
719 trees or describe the calculations made by the Java (or any other)
720 style.
721
722 You may be confused about how the different pixel metrics, sub
723 element rectangles, and sub control rectangles should be used when
724 examining the trees. If you are in doubt after reading the QStyle
725 enum descriptions, we suggest that you examine the QCommonStyle
726 implementation.
727
728 Some of the bounding rectangles that we outline in the widget
729 images are equal. Reasons for this are that some elements draw
730 backgrounds while others draw frames and labels. If in doubt,
731 check the description of each element in QStyle. Also, some
732 elements are there to layout, i.e., decide where to draw, other
733 elements.
734
735 \section2 Common Widget Properties
736
737 Some states and variables are common for all widgets. These are
738 set with QStyleOption::initFrom(). Not all elements use this function;
739 it is the widgets that create the style options, and for some
740 elements the information from \l{QStyleOption::}{initFrom()} is not
741 necessary.
742
743 A table with the common states follows:
744
745 \table 90%
746 \header
747 \li State
748 \li State Set When
749 \row
750 \li \c State_Enabled
751 \li Set if the widget is not disabled (see
752 QWidget::setEnabled())
753 \row
754 \li \c State_Focus
755 \li Set if the widget has focus (see
756 QWidget::hasFocus())
757 \row
758 \li \c State_KeyboardFocusChange
759 \li Set when the user changes focus with the keyboard
760 (see Qt::WA_KeyboardFocusChange)
761 \row
762 \li \c State_MouseOver
763 \li Set if the mouse cursor is over the widget
764 \row
765 \li \c State_Active
766 \li Set if the widget is a child of the active window.
767 \row
768 \li \c State_HasEditFocus
769 \li Set if the widget has the edit focus
770 \endtable
771
772 The other common members for widgets are:
773
774 \table 90%
775 \header
776 \li Member
777 \li Content
778 \row
779 \li rect
780 \li The bounding rectangle of the element to draw. This
781 is set to the widget bounding rectangle
782 (QWidget::rect()).
783 \row
784 \li direction
785 \li The layout direction; a value of the
786 Qt::LayoutDirection enum.
787 \row
788 \li palette
789 \li The QPalette to use when drawing the element. This
790 is set to the widgets palette (QWidget::palette()).
791 \row
792 \li fontMetrics
793 \li The QFontMetrics to use when drawing text on the
794 widget.
795 \endtable
796
797 The complex style options (classes that inherit
798 QStyleOptionComplex) used for complex style elements share two
799 variables: \l{QStyleOptionComplex::}{subControls} and
800 \l{QStyleOptionComplex::}{activeSubControls}. Both variables are
801 an OR'ed combination of QStyle::SubControl enum values. They
802 indicate which sub controls the complex control consists of and
803 which of these controls are currently active.
804
805 As mentioned, the style calculates the size of the widget's
806 contents, which the widgets calculate their size hints from. In
807 addition, complex controls also use the style to test which
808 sub-controls the mouse is over.
809
810 \section2 Widget Reference
811
812 Without further delay, we present the widget walkthrough; each
813 widget has its own sub-section.
814
815 \section3 Push Buttons
816
817 The style structure for push buttons is shown below. By doing a
818 top-down traversal of the tree, you get the sequence in which the
819 elements should be drawn.
820
821 \image javastyle/pushbutton.png
822 {Push button style tree and elements}
823
824 The layout of the buttons, with regard to element bounds, varies from
825 style to style. This makes it difficult to show conceptual images
826 of this. Also, elements may - even be intended to - have the same
827 bounds; the \c PE_PushButtonBevel, for instance, is used in
828 QCommonStyle to draw the elements that it contains:
829 \c PE_FrameDefaultButton, \c PE_FrameButtonBevel, and
830 \c PE_PanelButtonCommand, all of which have the same bounds in common
831 style. \c PE_PushButtonBevel is also responsible for drawing the menu
832 indicator (QCommonStyle draws \c PE_IndicatorArrowDown).
833
834 An image of a push button in the Java style that shows the bounding
835 rectangles of the elements is given below. Colors are used to
836 separate the bounding rectangles in the image; they do not fill
837 any other purpose. This is also true for similar images for the
838 other widgets.
839
840 \image javastyle/button.png {Button labeled with its elements}
841
842 The Java style, as well as all other styles implemented in Qt,
843 does not use \c PE_FrameButtonBevel. It is usual that a button
844 with a \c PE_DefaultFrame adjusts the \c PE_PanelButtonCommand's
845 rectangle by \c PM_ButtonDefaultIndicator. The \c CE_PushButtonLabel
846 is found by adjusting the rect by \c PM_DefaultFrameWidth.
847
848 We will now examine the style option for push
849 buttons - QStyleOptionButton. A table for the states that
850 QPushButton can set on the style option follows:
851
852 \table 90%
853 \header
854 \li State
855 \li State Set When
856 \row
857 \li \c State_Sunken
858 \li Button is down or menu is pressed shown
859 \row
860 \li \c State_On
861 \li Button is checked
862 \row
863 \li \c State_Raised
864 \li Button is not flat and not pressed down
865 \endtable
866
867 Other members of QStyleOptionButton are:
868
869 \table 90%
870 \header
871 \li Member
872 \li Content
873 \row
874 \li features
875 \li Flags of the QStyleOptionButton::ButtonFeatures enum,
876 which describes various button properties (see enum)
877 \row
878 \li icon
879 \li The buttons QIcon (if any)
880 \row
881 \li iconSize
882 \li The QSize of the icon
883 \row
884 \li text
885 \li a QString with the buttons text
886 \endtable
887
888 \section3 Check and Radio Buttons
889
890 The structures for radio and check buttons are identical.
891 We show the structure using QCheckBox element and pixel
892 metric names:
893
894 \image javastyle/checkbox.png
895 {Check and radio box style tree and elements}
896
897 QStyleOptionButton is used as the style option for both check
898 and radio buttons. We first give a table of the states that
899 can be set in the option:
900
901 \table 90%
902 \header
903 \li State
904 \li State Set When
905 \row
906 \li \c State_sunken
907 \li The box is pressed down
908 \row
909 \li \c State_NoChange
910 \li The box is partially checked (for tri-state
911 checkboxes.)
912 \row
913 \li \c State_On
914 \li The box is checked
915 \row
916 \li \c State_Off
917 \li The box is unchecked
918 \endtable
919
920 See \l{Push Buttons} for a table over other members in the
921 QStyleOptionButton class.
922
923 \section3 Tabs
924
925 In Qt, QTabBar uses the style to draw its tabs. Tabs exist either
926 in a QTabWidget, which contains a QTabBar, or as a separate bar.
927 If the bar is not part of a tab widget, it draws its own base.
928
929 QTabBar lays out the tabs, so the style does not have control over
930 tab placement. However, while laying out its tabs, the bar asks
931 the style for \c PM_TabBarTabHSpace and \c PM_TabBarTabVSpace, which is
932 extra width and height over the minimum size of the tab bar tab
933 label (icon and text). The style can also further influence the
934 tab size before it is laid out, as the tab bar asks for
935 \c CT_TabBarTab. The bounding rectangle of the bar is decided by the
936 tab widget when it is part of the widget (still considering
937 \c CT_TabBarTab).
938
939 The tab bar is responsible for drawing the buttons that appear on
940 the tab bar when all tabs do not fit. Their placement is not
941 controlled by the style, but the buttons are \l{QToolButton}s
942 and are therefore drawn by the style.
943
944 Here is the style structure for QTabWidget and QTabBar:
945
946 \image javastyle/tab.png
947 {Tab widget and tab bar style tree and elements}
948
949 The dotted lines indicate that the QTabWidget contains a tab bar,
950 but does not draw the tab bar itself. QTabBar only draws its base line
951 when not part of a tab widget, and it keeps two tool
952 buttons that scroll the bar when all tabs do not fit; see \l{Tool
953 Buttons} for their element tree. Also note that since the buttons
954 are children of the tab bar, they are drawn after the bar. The
955 tabs' bounding rectangles overlap the base by \c PM_TabBarBaseOverlap.
956
957 Here is a tab widget in the Java style:
958
959 \image javastyle/tabwidget.png {Tab widget labeled with its elements}
960
961 In the Java style, the tab bar shape and label have the same bounding
962 rectangle as \c CE_TabBarTab. Notice that the tabs overlap with the
963 tab widget frame. The base of the tab bar (if drawn) is the area where
964 the tabs and frame overlap.
965
966 The style option for tabs (QStyleOptionTab) contains the necessary
967 information for drawing tabs. The option contains the position of
968 the tab in the tab bar, the position of the selected tab, the
969 shape of the tab, the text, the icon, and the icon's size.
970
971 As the Java style tabs don't overlap, we also present an image of
972 a tab widget in the common style. Note that if you want the tabs
973 to overlap horizontally, you do that when drawing the tabs in
974 \c CE_TabBarTabShape; the tabs bounding rectangles will not be
975 altered by the tab bar. The tabs are drawn from left to right in a
976 north tab bar shape, top to bottom in an east tab bar shape, etc.
977 The selected tab is drawn last, so that it is easy to draw it over
978 the other tabs (if it is to be bigger).
979
980 \image javastyle/windowstabimage.png
981 {Tab bar labeled with its elements}
982
983 A table of the states a tab bar can set on its tabs follows:
984
985 \table 90%
986 \header
987 \li State
988 \li State Set When
989 \row
990 \li \c State_Sunken
991 \li The tab is pressed on with the mouse.
992 \row
993 \li \c State_Selected
994 \li If it is the current tab.
995 \row
996 \li \c State_HasFocus
997 \li The tab bar has focus and the tab is selected.
998 \endtable
999
1000 Note that individual tabs may be disabled even if the tab bar
1001 is not. The tab will be active if the tab bar is active.
1002
1003 Here follows a table of QStyleOptionTab's members:
1004
1005 \table 90%
1006 \header
1007 \li Member
1008 \li Content
1009 \row
1010 \li cornerWidgets
1011 \li Flags of the CornerWidget enum, which indicate
1012 if and which corner widgets the tab bar has.
1013 \row
1014 \li icon
1015 \li The QIcon of the tab.
1016 \row
1017 \li iconSize
1018 \li The QSize of the icon.
1019 \row
1020 \li position
1021 \li A TabPosition enum value that indicates the tab's
1022 position on the bar relative to the other tabs.
1023 \row
1024 \li row
1025 \li Holds which row the tab is in.
1026 \row
1027 \li selectedPosition
1028 \li A value of the SelectedPosition enum that indicates
1029 whether the selected tab is adjacent to or is the
1030 tab.
1031 \row
1032 \li shape
1033 \li A value of the QTabBar::Shape enum indicating
1034 whether the tab has rounded or triangular corners
1035 and the orientation of the tab.
1036 \row
1037 \li text
1038 \li The tab text.
1039 \endtable
1040
1041 The frame for tab widgets use QStyleOptionTabWidgetFrame as
1042 style option. We list its members here. It does not have
1043 states set besides the common flags.
1044
1045 \table 90%
1046 \header
1047 \li Member
1048 \li content
1049 \row
1050 \li leftCornerWidgetSize
1051 \li The QSize of the left corner widget (if any).
1052 \row
1053 \li rightCornerWidgetSize
1054 \li The QSize of the right corner widget (if any).
1055 \row
1056 \li lineWidth
1057 \li Holds the line with for drawing the panel.
1058 \row
1059 \li midLineWith
1060 \li This value is currently always 0.
1061 \row
1062 \li shape
1063 \li The shape of the tabs on the tab bar.
1064 \row
1065 \li tabBarSize
1066 \li The QSize of the tab bar.
1067 \endtable
1068
1069 \section3 Scroll Bars
1070
1071 Here is the style structure for scrollbars:
1072
1073 \image javastyle/scrollbar.png
1074 {Scrollbar style tree and elements}
1075
1076 QScrollBar simply creates its style option and then draws
1077 \c CC_ScrollBar. Some styles draw the background of add page and sub
1078 page with \c PE_PanelButtonBevel, and also use indicator arrows to
1079 draw the arrows in the next and previous line indicators; we have
1080 not included these in the tree as their use is up to the
1081 individual style. The style's \c PM_MaximumDragDistance is the
1082 maximum distance in pixels the mouse can move from the bounds
1083 of the scroll bar and still move the handle.
1084
1085 Here is an image of a scrollbar in the Java style:
1086
1087 \image javastyle/scrollbarimage.png
1088 {Scrollbar labeled with its elements}
1089
1090 You may notice that the scrollbar is slightly different from
1091 Java's, as it has two line up indicators. We have done this to show
1092 that you can have two separate bounding rectangles for a
1093 single sub control. The scroll bar is an example of a widget that
1094 is entirely implemented by the Java style - QCommonStyle is not
1095 involved in the drawing.
1096
1097 We have a look at the different states a scroll bar can set on
1098 the style option:
1099
1100 \table 90%
1101 \header
1102 \li State
1103 \li State Set When
1104 \row
1105 \li \c State_Horizontal
1106 \li The scroll bar is horizontal.
1107 \endtable
1108
1109 The style option of QScrollBar is QStyleOptionSlider. Its
1110 members are listed in the following table. The option is used
1111 by all \l{QAbstractSlider}s; we only describe the members
1112 relevant for scroll bars here.
1113
1114 \table 90%
1115 \header
1116 \li Member
1117 \li Content
1118 \row
1119 \li maximum
1120 \li The maximum value of the scroll bar.
1121 \row
1122 \li minimum
1123 \li The minimum value of the scroll bar.
1124 \row
1125 \li notchTarget
1126 \li The number of pixels between notches.
1127 \row
1128 \li orientation
1129 \li A value of the Qt::Orientation enum that specifies
1130 whether the scroll bar is vertical or horizontal.
1131 \row
1132 \li pageStep
1133 \li The number by which to increase or decrease the slider's
1134 value (relative to the size of the slider and its value
1135 range) on page steps.
1136 \row
1137 \li singleStep
1138 \li The number by which to increase or decrease the slider's
1139 value on single (or line) steps.
1140 \row
1141 \li sliderValue
1142 \li The value of the slider.
1143 \row
1144 \li sliderPosition
1145 \li The position of the slider handle. This is the same
1146 as \c sliderValue if the scroll bar is
1147 QAbstractSlider::tracking. If not, the scroll
1148 bar does not update its value before the mouse
1149 releases the handle.
1150 \row
1151 \li upsideDown
1152 \li Holds the direction in which the scroll bar
1153 increases its value. This is used instead of
1154 QStyleOption::direction for all abstract sliders.
1155 \endtable
1156
1157 \section3 Sliders
1158
1159 When calculating the slider's size hint, \c PM_SliderThickness and
1160 \c PM_SliderLength are queried from the style. As with scroll bars,
1161 the QSlider only lets the user move the handle if the mouse is
1162 within \c PM_MaximumDragDistance from the slider bounds. When it
1163 draws itself, it creates the style option and calls \c
1164 drawComplexControl() with \c CC_Slider:
1165
1166 \image javastyle/slider.png {Slider style tree and elements}
1167
1168 We also show a picture of a slider in the Java style. We show
1169 the bounding rectangles of the sub elements, as all drawing is done
1170 in \c CC_Slider.
1171
1172 \image javastyle/sliderimage.png {Slider labeled with its elements}
1173
1174 QSlider uses QStyleOptionSlider as all \l{QAbstractSlider}s do. We
1175 present a table with the members that affect QSlider:
1176
1177 \table 90%
1178 \header
1179 \li Member
1180 \li Content
1181 \row
1182 \li maximum
1183 \li The maximum value of the slider.
1184 \row
1185 \li minimum
1186 \li The minimum value of the slider.
1187 \row
1188 \li notchTarget
1189 \li This is the number of pixels between each notch.
1190 \row
1191 \li orientation
1192 \li A Qt::Orientation enum value that indicates whether the
1193 slider is vertical or horizontal.
1194 \row
1195 \li pageStep
1196 \li The number by which to increase or decrease the slider's
1197 value on page steps.
1198 \row
1199 \li singleStep
1200 \li The number by which to increase or decrease the slider's
1201 value on single (or line) steps.
1202 \row
1203 \li sliderValue
1204 \li The value of the slider.
1205 \row
1206 \li sliderPosition
1207 \li The position of the slider given as a slider value.
1208 This will be equal to the \c sliderValue if the
1209 slider is \l{QAbstractSlider::}{tracking}; if
1210 not, the slider's value will not change until the handle is
1211 released with the mouse.
1212 \row
1213 \li upsideDown
1214 \li This member is used instead of QStyleOption::direction
1215 for all abstract sliders.
1216 \endtable
1217
1218 You should note that the slider does not use direction for
1219 reverse layouts; it uses \c upsideDown.
1220
1221 \section3 Spin Boxes
1222
1223 When QSpinBox paints itself, it creates a QStyleOptionSpinBox and
1224 asks the style to draw \c CC_SpinBox. The edit field is a line
1225 edit that is a child of the spin box. The dimensions of the
1226 field are calculated by the style with \c SC_SpinBoxEditField.
1227
1228 Here follows the style tree for spin boxes. It is not
1229 required that a style uses the button panel primitive to paint
1230 the indicator backgrounds. You can see an image below the tree
1231 showing the sub elements in QSpinBox in the Java style.
1232
1233 \image javastyle/spinbox.png {Spin box style tree and elements}
1234
1235 \image javastyle/spinboximage.png {Spin box labeled with its elements}
1236
1237 The QStyleOptionSpinBox, which is the style option for spin
1238 boxes. It can set the following states on the spin box:
1239
1240 \table 90%
1241 \header
1242 \li State
1243 \li State Set When
1244 \row
1245 \li \c State_Sunken
1246 \li Is set if one of the sub controls \c CC_SpinUp or
1247 \c CC_SpinDown is pressed on with the mouse.
1248 \endtable
1249
1250 The rest of the members in the spin box style options are:
1251
1252 \table 90%
1253 \header
1254 \li Property
1255 \li Function
1256 \row
1257 \li frame
1258 \li Boolean that is \c true if the spin box is to draw a
1259 frame.
1260 \row
1261 \li buttonSymbols
1262 \li Value of the ButtonSymbols enum that decides the
1263 symbol on the up/down buttons.
1264 \row
1265 \li stepEnabled
1266 \li A value of the StepEnabled enum, indicating which of the
1267 spin box buttons are pressed down.
1268 \endtable
1269
1270 \section3 Title Bar
1271
1272 The title bar complex control, \c CC_TitleBar, is used to draw
1273 the title bars of internal windows in QMdiArea. It typically
1274 consists of a window title, and close, minimize, system menu, and
1275 maximize buttons. Some styles also provide buttons for shading
1276 the window, as well as a button for context sensitive help.
1277
1278 The bar is drawn in \c CC_TitleBar without using any sub elements.
1279 How the individual styles draw their buttons is up to them, but
1280 there are standard pixmaps for the buttons that the style should
1281 provide.
1282
1283 \image javastyle/titlebar.png
1284 {Title bar style tree and elements}
1285
1286 In an image over a title bar in the Java style, we show the
1287 bounding rectangles of the sub elements supported by the Java style
1288 (all of which are drawn with standard pixmaps). It is usual to
1289 draw the button backgrounds using \c PE_PanelButtonTool, but it's not
1290 mandatory.
1291
1292 \image javastyle/titlebarimage.png
1293 {Title bar labeled with its elements}
1294
1295 The style option for title bars is QStyleOptionTitleBar. Its
1296 members are:
1297
1298 \table 90%
1299 \header
1300 \li Member
1301 \li Content
1302 \row
1303 \li icon
1304 \li The title bar's icon.
1305 \row
1306 \li text
1307 \li The text for the title bar's label.
1308 \row
1309 \li windowFlags
1310 \li Flags of the Qt::WindowFlag enum. The window flags
1311 used by QMdiArea for window management.
1312 \row
1313 \li titleBarState
1314 \li This is the QWidget::windowState() of the window
1315 that contains the title bar.
1316 \endtable
1317
1318 \section3 Combo Box
1319
1320 A QComboBox uses the style to draw the button and label of
1321 non-editable boxes with \c CC_ComboBox and \c CE_ComboBoxLabel.
1322
1323 The list that pops up when the user clicks on the combo box is
1324 drawn by a \l{Delegate Classes}{delegate}, which we do not cover
1325 in this overview. You can, however, use the style to control the
1326 list's size and position with the sub element
1327 \c SC_ComboBoxListBoxPopup. The style also decides where the edit
1328 field for editable boxes should be with \c SC_ComboBoxEditField; the
1329 field itself is a QLineEdit that is a child of the combo box.
1330
1331 \image javastyle/combobox.png
1332 {Combo box style tree and elements}
1333
1334 We show an image over a Java style combo box in which we have
1335 outlined its sub elements and sub element rectangles:
1336
1337 \image javastyle/comboboximage.png
1338 {Combo box labeled with its elements}
1339
1340 Java combo boxes do not use the focus rect; it changes its
1341 background color when it has focus. The \c SC_ComboBoxEdit field is
1342 used both by QComboBox to calculate the size of the edit field and
1343 the style for calculating the size of the combo box label.
1344
1345 The style option for combo boxes is QStyleOptionComboBox. It
1346 can set the following states:
1347
1348 \table 90%
1349 \header
1350 \li State
1351 \li Set When
1352 \row
1353 \li \c State_Selected
1354 \li The box is not editable and has focus.
1355 \row
1356 \li \c State_Sunken
1357 \li \c SC_ComboBoxArrow is active.
1358 \row
1359 \li \c State_on
1360 \li The container (list) of the box is visible.
1361 \endtable
1362
1363 The style options other members are:
1364
1365 \table
1366 \header
1367 \li Member
1368 \li Content
1369 \row
1370 \li currentIcon
1371 \li The icon of the current (selected) item of the
1372 combo box.
1373 \row
1374 \li currentText
1375 \li The text of the current item in the box.
1376 \row
1377 \li editable
1378 \li Holds whether the combo box is editable or not.
1379 \row
1380 \li frame
1381 \li Holds whether the combo box has a frame or not.
1382 \row
1383 \li iconSize
1384 \li The size of the current items icon.
1385 \row
1386 \li popupRect
1387 \li The bounding rectangle of the combo box's popup
1388 list.
1389 \endtable
1390
1391 \section3 Group Boxes
1392
1393 When calculating the size hint, QGroupBox fetches three pixel
1394 metrics from the style: \c PM_IndicatorWidth,
1395 \c PM_CheckBoxLabelSpacing, and \c PM_IndicatorHeight. QGroupBox has
1396 the following style element tree:
1397
1398 \image javastyle/groupbox.png
1399 {Group box style tree and elements}
1400
1401 Qt does not impose restrictions on how the check box is drawn; the
1402 Java style draws it with \c CE_IndicatorCheckBox. See \l{Check and
1403 Radio Buttons} for the complete tree.
1404
1405 We also give an image of the widget with the sub controls and
1406 sub control rectangles drawn:
1407
1408 \image javastyle/groupboximage.png
1409 {Group box labeled with its elements}
1410
1411 The style option for group boxes is QStyleOptionGroupBox. The
1412 following states can be set on it:
1413
1414 \table 90%
1415 \header
1416 \li State
1417 \li Set When
1418 \row
1419 \li \c State_On
1420 \li The check box is checked.
1421 \row
1422 \li \c State_Sunken
1423 \li The check box is pressed down.
1424 \row
1425 \li \c State_Off
1426 \li The check box is unchecked (or there is no check box).
1427 \endtable
1428
1429 The remaining members of QStyleOptionGroupBox are:
1430
1431 \table
1432 \header
1433 \li Member
1434 \li Content
1435 \row
1436 \li features
1437 \li Flags of the QStyleOptionFrame::FrameFeatures
1438 enum describing the frame of the group box.
1439 \row
1440 \li lineWidth
1441 \li The line width with which to draw the panel. This
1442 is always 1.
1443 \row
1444 \li text
1445 \li The text of the group box.
1446 \row
1447 \li textAlignment
1448 \li The alignment of the group box title.
1449 \row
1450 \li textColor
1451 \li The QColor of the text.
1452 \endtable
1453
1454 \section3 Splitters
1455
1456 As the structure of splitters are simple and do not contain any
1457 sub elements, we do not include any images of splitters. \c CE_Splitter
1458 does not use any other elements or metrics.
1459
1460 For its style option, the splitter uses the base class QStyleOption.
1461 It can set the following state flags on it:
1462
1463 \table 90%
1464 \header
1465 \li State
1466 \li Set When
1467 \row
1468 \li \c State_Horizontal
1469 \li Set if it is a horizontal splitter.
1470 \endtable
1471
1472 QSplitter does not use \l{QStyleOption::}{initFrom()} to set up its
1473 option; it sets the \c State_MouseOver and \c State_Disabled flags
1474 itself.
1475
1476 \section3 Progress Bar
1477
1478 The \c CE_ProgressBar element is used by QProgressBar, and it is the
1479 only element used by this widget. We start with the style structure:
1480
1481 \image javastyle/progressbar.png
1482 {Progress bar style tree and elements}
1483
1484 Here is a progress bar in the common style (the Java style
1485 bounding rectangles are equal):
1486
1487 \image javastyle/progressbarimage.png
1488 {Progress bar labeled with its elements}
1489
1490 The style option for QProgressBar is QStyleOptionProgressBar.
1491 The bar does not set any state flags, but the other members of the
1492 option are:
1493
1494 \table 90%
1495 \header
1496 \li Member
1497 \li Content
1498 \row
1499 \li minimum
1500 \li The minimum value of the bar.
1501 \row
1502 \li maximum
1503 \li The maximum value of the bar.
1504 \row
1505 \li progress
1506 \li The current value of the bar.
1507 \row
1508 \li textAlignment
1509 \li How the text is aligned in the label.
1510 \row
1511 \li textVisible
1512 \li Whether the label is drawn.
1513 \row
1514 \li text
1515 \li The label text.
1516 \row
1517 \li orientation
1518 \li Progress bars can be vertical or horizontal.
1519 \row
1520 \li invertedAppearance
1521 \li The progress is inverted (i.e., right to left in a
1522 horizontal bar).
1523 \row
1524 \li bottomToTop
1525 \li Boolean, that, if \c true, turns the label of vertical
1526 progress bars 90 degrees.
1527 \endtable
1528
1529 \section3 Tool Buttons
1530
1531 Tool buttons exist either independently or as part of tool bars.
1532 They are drawn equally either way. The QToolButton draws only one
1533 style element: \c CC_ToolButton.
1534
1535 Below is a tree of the widget's style structure:
1536
1537 \image javastyle/toolbutton.png
1538 {Tool button style tree and elements}
1539
1540 Note that \c PE_FrameButtonTool and \c PE_IndicatorArrowDown are
1541 included in the tree as the Java style draws them, but they can
1542 safely be omitted if you prefer it. The structure may also be
1543 different. QCommonStyle, for instance, draws both
1544 \c PE_IndicatorButtonDropDown and \c PE_IndicatorArrowDown in
1545 \c CE_ToolButton.
1546
1547 We also have an image of a tool button where we have outlined
1548 the sub element bounding rectangles and sub controls.
1549
1550 \image javastyle/toolbuttonimage.png
1551 {Tool button labeled with its elements}
1552
1553 Here is the states table for tool buttons:
1554
1555 \table 90%
1556 \header
1557 \li State
1558 \li Set When
1559 \row
1560 \li \c State_AutoRise
1561 \li The tool button has the autoRise property set.
1562 \row
1563 \li \c State_Raised
1564 \li The button is not sunken (i.e., by being checked or
1565 pressed on with the mouse).
1566 \row
1567 \li \c State_Sunken
1568 \li The button is down.
1569 \row
1570 \li \c State_On
1571 \li The button is checkable and checked.
1572 \endtable
1573
1574 QStyleOptionToolButton also contains the following members:
1575
1576 \table
1577 \header
1578 \li Member
1579 \li Content
1580 \row
1581 \li arrowType
1582 \li A Qt::ArrowType enum value, which contains the
1583 direction of the buttons arrow (if an arrow is to
1584 be used in place of an icon).
1585 \row
1586 \li features
1587 \li Flags of the QStyleOptionToolButton::ButtonFeature
1588 enum describing if the button has an arrow, a menu,
1589 and/or has a popup-delay.
1590 \row
1591 \li font
1592 \li The QFont of the buttons label.
1593 \row
1594 \li icon
1595 \li The QIcon of the tool button.
1596 \row
1597 \li iconSize
1598 \li The icon size of the button's icon.
1599 \row
1600 \li pos
1601 \li The position of the button, as given by
1602 QWidget::pos()
1603 \row
1604 \li text
1605 \li The text of the button.
1606 \row
1607 \li toolButtonStyle
1608 \li A Qt::ToolButtonStyle enum value which decides
1609 whether the button shows the icon, the text, or both.
1610 \endtable
1611
1612 \section3 Toolbars
1613
1614 Toolbars are part of the \l{QMainWindow}{main window framework},
1615 and cooperate with the QMainWindow to which they belong while it
1616 builds its style option. A main window has 4 areas that toolbars
1617 can be placed in. They are positioned next to the four sides of
1618 the window (i.e., north, south, east and west). Within each area
1619 there can be more than one line of toolbars; a line consists of
1620 toolbars with equal orientation (vertical or horizontal) placed
1621 next to each other.
1622
1623 \l{QToolBar}{Toolbars} in Qt consist of three elements:
1624 \c CE_ToolBar, \c PE_IndicatorToolBarHandle, and
1625 \c PE_IndicatorToolBarSeparator. It is QMainWindowLayout that
1626 calculates the bounding rectangles (i.e., position and size of the
1627 toolbars and their contents. The main window also uses the \c
1628 sizeHint() of the items in the toolbars when calculating the size
1629 of the bars.
1630
1631 Here is the element tree for QToolBar:
1632
1633 \image javastyle/toolbar.png
1634 {Tool bar style tree and elements}
1635
1636 The dotted lines indicate that the QToolBar keeps an instance of
1637 QToolBarLayout and that QToolBarSeparators are kept by
1638 QToolBarLayout. When the toolbar is floating (i.e., has its own
1639 window) the \c PE_FrameMenu element is drawn, else QToolBar draws
1640 \c CE_ToolBar.
1641
1642 Here is an image of a toolbar in the Java style:
1643
1644 \image javastyle/toolbarimage.png
1645 {Tool bar labeled with its elements}
1646
1647 QToolBarSaparator uses QStyleOption for its style option. It
1648 sets the \c State_Horizontal flag if the toolbar it lives in is
1649 horizontal. Other than that, they use \l{QStyleOption::}{initFrom()}.
1650
1651 The style option for QToolBar is QStyleOptionToolBar. The only
1652 state flag set (besides the common flags) is \c State_Horizontal
1653 if the bar is horizontal (i.e., in the north or south toolbar area).
1654 The member variables of the style option are:
1655
1656 \table 90%
1657 \header
1658 \li Member
1659 \li Content
1660 \row
1661 \li features
1662 \li Holds whether the bar is movable in a value of the
1663 ToolBarFeature, which is either Movable or None.
1664 \row
1665 \li lineWidth
1666 \li The width of the tool bar frame.
1667 \row
1668 \li midLineWidth
1669 \li This variable is currently not used and is always 0.
1670 \row
1671 \li positionOfLine
1672 \li The position of the toolbar line within the toolbar
1673 area to which it belongs.
1674 \row
1675 \li positionWithinLine
1676 \li The position of the toolbar within the toolbar line.
1677 \row
1678 \li toolBarArea
1679 \li The toolbar area in which the toolbar lives.
1680 \endtable
1681
1682 \section3 Menus
1683
1684 Menus in Qt are implemented in QMenu. The QMenu keeps a list of
1685 actions, which it draws as menu items. When QMenu receives paint
1686 events, it calculates the size of each menu item and draws them
1687 individually with \c CE_MenuItem. Menu items do not have a separate
1688 element for their label (contents), so all drawing is done in
1689 \c CE_MenuItem. The menu also draws the frame of the menu with
1690 \c PE_FrameMenu. It also draws \c CE_MenuScroller if the style supports
1691 scrolling. \c CE_MenuTearOff is drawn if the menu is too large for its
1692 bounding rectangle.
1693
1694 In the style structure tree, we also include QMenu as it also does
1695 styling related work. The bounding rectangles of menu items are
1696 calculated for the menu's size hint and when the menu is displayed
1697 or resized.
1698
1699 \image javastyle/menu.png {Menu style tree and elements}
1700
1701 The \c CE_MenuScroller and \c CE_MenuTearOff elements are handled by
1702 QCommonStyle and are not shown unless the menu is too large to fit
1703 on the screen. \c PE_FrameMenu is only drawn for pop-up menus.
1704
1705 QMenu calculates rectangles based on its actions and calls
1706 \c CE_MenuItem and \c CE_MenuScroller if the style supports that.
1707
1708 It is also usual to use \c PE_IndicatorCheckBox (instead of using
1709 \c PE_IndicatorMenuCheckMark) and \c PE_IndicatorRadioButton for drawing
1710 checkable menu items; we have not included them in the style tree
1711 as this is optional and varies from style to style.
1712
1713 \image javastyle/menuimage.png
1714 {Menu labeled with its elements}
1715
1716 The style option for menu items is QStyleOptionMenuItem. The
1717 following tables describe its state flags and other members.
1718
1719 \table 90%
1720 \header
1721 \li State
1722 \li Set When
1723 \row
1724 \li \c State_Selected
1725 \li The mouse is over the action and the action is not
1726 a separator.
1727 \row
1728 \li \c State_Sunken
1729 \li The mouse is pressed down on the menu item.
1730 \row
1731 \li \c State_DownArrow
1732 \li Set if the menu item is a menu scroller and it scrolls
1733 the menu downwards.
1734 \endtable
1735
1736 \table 90%
1737 \header
1738 \li Member
1739 \li Content
1740 \row
1741 \li checkType
1742 \li A value of the \l{QStyleOptionMenuItem::}{CheckType} enum,
1743 which is either NotCheckable, Exclusive, or
1744 NonExclusive.
1745 \row
1746 \li checked
1747 \li Boolean that is \c true if the menu item is checked.
1748 \row
1749 \li font
1750 \li The QFont to use for the menu item's text.
1751 \row
1752 \li icon
1753 \li The QIcon of the menu item.
1754 \row
1755 \li maxIconWidth
1756 \li The maximum width allowed for the icon.
1757 \row
1758 \li menuHasCheckableItems
1759 \li Boolean which is \c true if at least one item in the
1760 menu is checkable.
1761 \row
1762 \li menuItemType
1763 \li The type of the menu item. This a value of the
1764 \l{QStyleOptionMenuItem::}{MenuItemType}.
1765 \row
1766 \li menuRect
1767 \li The bounding rectangle for the QMenu that the menu
1768 item lives in.
1769 \row
1770 \li tabWidth
1771 \li This is the distance between the text of the menu
1772 item and the shortcut.
1773 \row
1774 \li text
1775 \li The text of the menu item.
1776 \endtable
1777
1778 The setup of the style option for \c CE_MenuTearOff and
1779 \c CE_MenuScroller also uses QStyleOptionMenuItem; they only set the
1780 \c menuRect variable in addition to the common settings with
1781 QStyleOption's \l{QStyleOption::}{initFrom()}.
1782
1783 \section3 Menu Bar
1784
1785 QMenuBar uses the style to draw each menu bar item and the empty
1786 area of the menu bar. The pull-down menus themselves are
1787 \l{QMenu}s (see \l{Menus}). The style element tree for the menu
1788 bar follows:
1789
1790 \image javastyle/menubar.png
1791 {Menu bar style tree and elements}
1792
1793 The panel and empty area are drawn after the menu items. The
1794 QPainter that the QMenuBar sends to the style has the bounding
1795 rectangles of the items clipped out (i.e., clip region), so you
1796 don't need to worry about drawing over the items. The pixel
1797 metrics in QMenuBar are used when the bounding rectangles of the
1798 menu bar items are calculated.
1799
1800 \image javastyle/menubarimage.png
1801 {Menu bar labeled with its elements}
1802
1803 QStyleOptionMenuItem is used for menu bar items. The members that
1804 are used by QMenuBar are described in the following table:
1805
1806 \table
1807 \header
1808 \li Member
1809 \li Content
1810 \row
1811 \li menuRect
1812 \li The bounding rectangle of the entire menu bar to
1813 which the item belongs.
1814 \row
1815 \li text
1816 \li The text of the item.
1817 \row
1818 \li icon
1819 \li The icon of the menu item (it is not common that
1820 styles draw this icon).
1821 \endtable
1822
1823 QStyleOptionMenuItem is also used for drawing \c CE_EmptyMenuBarArea.
1824
1825 QStyleOptionFrame is used for drawing the panel frame. The
1826 \l{QStyleOptionFrame::}{lineWidth} is set to \c PM_MenuBarPanelWidth.
1827 The \l{QStyleOptionFrame::}{midLineWidth} is currently always set
1828 to 0.
1829
1830 \section3 Item View Headers
1831
1832 It is the style that draws the headers of Qt's item views. The
1833 item views keep the dimensions on individual sections. Also
1834 note that the delegates may use the style to paint decorations
1835 and frames around items. QItemDelegate, for instance, draws
1836 \c PE_FrameFocusRect and \c PE_IndicatorItemViewItemCheck.
1837
1838 \image javastyle/header.png
1839 {Header style tree and elements}
1840
1841 Here is a QTableWidget showing the bounding rects of a Java
1842 header:
1843
1844 \image javastyle/headerimage.png
1845 {Header labeled with its elements}
1846
1847 The QHeaderView uses \c CT_HeaderSection, \c PM_HeaderMargin and
1848 \c PM_HeaderGripMargin for size and hit test calculations. The
1849 \c PM_HeaderMarkSize is currently not used by Qt. QTableView draws
1850 the button in the top-left corner (i.e., the area where the
1851 vertical and horizontal headers intersect) as a \c CE_Header.
1852
1853 The style option for header views is QStyleOptionHeader. The view
1854 paints one header section at a time, so the data is for the
1855 section being drawn. Its contents are:
1856
1857 \table 90%
1858 \header
1859 \li Member
1860 \li Content
1861 \row
1862 \li icon
1863 \li The icon of the header (for section that is being drawn).
1864 \row
1865 \li iconAlignment
1866 \li The alignment (Qt::Alignment) of the icon in the header.
1867 \row
1868 \li orientation
1869 \li A Qt::Orientation value deciding whether the header
1870 is the horizontal header above the view or the
1871 vertical header on the left.
1872 \row
1873 \li position
1874 \li A QStyleOptionHeader::SectionPosition value
1875 giving the header section's position relative to
1876 the other sections.
1877 \row
1878 \li section
1879 \li Holds the section that is being drawn.
1880 \row
1881 \li selectedPosition
1882 \li A QStyleOptionHeader::SelectedPosition value giving
1883 the selected section's position relative to the
1884 section that is being painted.
1885 \row
1886 \li sortIndicator
1887 \li A QStyleOptionHeader::SortIndicator value that
1888 describes the direction in which the section's sort
1889 indicator should be drawn.
1890 \row
1891 \li text
1892 \li The text of the currently drawn section.
1893 \row
1894 \li textAlignment
1895 \li The Qt::Alignment of the text within the header section.
1896 \endtable
1897
1898 \section3 Tree Branch Indicators
1899
1900 The branch indicators in a tree view are drawn by the style with
1901 \c PE_IndicatorBranch. We think of indicators here as the indicators
1902 that describe the relationship of the nodes in the tree. The
1903 generic QStyleOption is sent to the style for drawing these
1904 elements. The various branch types are described by states. Since
1905 there is no specific style option, we simply present the states
1906 table:
1907
1908 \table 90%
1909 \header
1910 \li State
1911 \li Set When
1912 \row
1913 \li \c State_Sibling
1914 \li The node in the tree has a sibling (i.e., there is
1915 another node in the same column).
1916 \row
1917 \li \c State_Item
1918 \li This branch indicator has an item.
1919 \row
1920 \li \c State_Children
1921 \li The branch has children (i.e., a new sub-tree can
1922 be opened at the branch).
1923 \row
1924 \li \c State_Open
1925 \li The branch indicator has an opened sub-tree.
1926 \endtable
1927
1928 The tree view (and tree widget) use the style to draw the branches
1929 (nodes) of the tree.
1930
1931 QStyleOption is used as the style for \c PE_IndicatorBranch has state
1932 flags set depending on what type of branch it is.
1933
1934 Since there is no tree structure for branch indicators, we only
1935 present an image of a tree in the Java style. Each state is marked
1936 in the image with a rectangle in a specific color (i.e., the
1937 rectangles are not bounding rectangles). All combinations of
1938 states you must be aware of are represented in the image.
1939
1940 \image javastyle/branchindicatorimage.png
1941 {Branch indicator style structure and drawing states}
1942
1943 \section3 Tool Boxes
1944
1945 \c PM_SmallIconSize for sizeHints.
1946
1947 QToolBox is a container that keeps a collection of widgets. It has
1948 one tab for each widget and displays one of them at a time. The
1949 tool box lays the components it displays (the tool box buttons
1950 and selected widget) in a QVBoxLayout. The style tree for tool
1951 boxes looks like this:
1952
1953 \image javastyle/toolbox.png
1954 {Tool box style tree and elements}
1955
1956 We show an image of a tool box in the Plastique style:
1957
1958 \image javastyle/toolboximage.png
1959 {Tool box labeled with its elements}
1960
1961 All elements have the same bounding rectangles in the
1962 Plastique style as well as the other built-in Qt styles.
1963
1964 The style option for tool boxes is QStyleOptionToolBox. It
1965 contains the text and icon of the tool box contents. The only
1966 state set by QToolBox is \c State_Sunken, which is set when the user
1967 presses a tab down with the mouse. The rest of the
1968 QStyleOptionToolBox members are:
1969
1970 \table 90%
1971 \header
1972 \li Member
1973 \li Content
1974 \row
1975 \li icon
1976 \li The icon on the toolbox tab.
1977 \row
1978 \li text
1979 \li The text on the toolbox tab.
1980 \endtable
1981
1982 \section3 Size Grip
1983
1984 The size grip calculates its size hint with \c CT_SizeGrip. The pixel
1985 metric \c PM_SizeGripSize is currently unused by Qt. The element tree
1986 for an image in the Plastique style of QSizeGrip follows:
1987
1988 \image javastyle/sizegrip.png {Size grip style tree and elements}
1989
1990 \image javastyle/sizegripimage.png {Size grip labeled with its elements}
1991
1992 We show the size grip in \l{QMainWindow}'s bottom right
1993 corner.
1994
1995 The size grip style option, QStyleOptionSizeGrip, has one
1996 member besides the common members from QStyleOption:
1997
1998 \table 90%
1999 \header
2000 \li Member
2001 \li Content
2002 \row
2003 \li corner
2004 \li A Qt::Corner value that describes which corner in a
2005 window (or equivalent) the grip is located.
2006 \endtable
2007
2008 \section3 Rubber Band
2009
2010 The \l{QRubberBand}'s style tree consists of two nodes.
2011
2012 \image javastyle/rubberband.png {Rubber band style tree and its elements}
2013
2014 We present an image of a Java style window being moved in a
2015 QMdiArea with a rubber band:
2016
2017 \image javastyle/rubberbandimage.png
2018 {Rubber band labeled with its elements}
2019
2020 The style option for rubber bands is QStyleOptionRubberBand.
2021 Its members are:
2022
2023 \table
2024 \header
2025 \li Member
2026 \li Content
2027 \row
2028 \li opaque
2029 \li Boolean that is \c true if the rubber band must be
2030 drawn in an opaque style (i.e., color).
2031 \row
2032 \li shape
2033 \li A QRubberBand::Shape enum value that holds the
2034 shape of the band (which is either a rectangle or a
2035 line).
2036 \endtable
2037
2038 \section3 Dock Widgets
2039
2040 When the dock widget lays out its contents it asks the style for
2041 these pixel metrics: \c PM_DockWidgetSeparatorExtent,
2042 \c PM_DockWidgetTitleBarButtonMargin, \c PM_DockWidgetFrameWidth, and
2043 \c PM_DockWidgetTitleMargin. It also calculates the bounding
2044 rectangles of the float and close buttons with
2045 \c SE_DockWidgetCloseButton and \c SE_DockWidgetFloatButton.
2046
2047 \image javastyle/dockwidget.png {Dock widget style tree and elements}
2048
2049 The dotted lines indicate that the sender keeps instances of the
2050 recipient of the arrow (i.e., it is not a style element to draw).
2051 The dock widget only draws \c PE_frameDockWidget when it is detached
2052 from its main window (i.e., it is a top level window). If it is
2053 docked it draws the indicator dock widget resize handle. We show a
2054 dock widget in both docked and floating state in the plastique
2055 style:
2056
2057 \image javastyle/dockwidgetimage.png {Dock widget labeled with its elements}
2058
2059 The style option is QStyleOptionDockWidget:
2060
2061 \table 90%
2062 \header
2063 \li Member
2064 \li Content
2065 \row
2066 \li closeable
2067 \li Boolean that holds whether the dock window can be
2068 closed.
2069 \row
2070 \li floatable
2071 \li Boolean that holds whether the dock window can
2072 float (i.e., detach from the main window in which
2073 it lives).
2074 \row
2075 \li movable
2076 \li Boolean that holds whether the window is movable
2077 (i.e., can move to other dock widget areas).
2078 \row
2079 \li title
2080 \li The title text of the dock window.
2081 \endtable
2082
2083 For the buttons, QStyleOptionButton is used (see \l{Tool Buttons}
2084 for content description). The dock widget resize handle has a
2085 plain QStyleOption.
2086*/