1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
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.
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
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().
21 \section1 Customizing a Style
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.
32 \section1 Implementing a Custom Style
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.
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.
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.
55 \section1 Classes for Widget Styling
57 These classes are used to customize an application's appearance and
60 \annotatedlist appearance
62 \section1 The QStyle Implementation
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.
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:
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)
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
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.
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.
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).
111 \section2 The Style Elements
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.
123 \image javastyle/conceptualpushbuttontree.png
125 Widgets are not necessarily drawn by asking the style to draw
126 only one element. Widgets can make several calls to the style to
127 draw different elements. An example is QTabWidget, which draws its
128 tabs and frame individually.
130 There are three element types: primitive elements, control
131 elements, and complex control elements. The elements are defined
132 by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement},
133 and \l{QStyle::}{PrimitiveElement} enums. The values of
134 each element enum has a prefix to identify their type: \c{CC_} for
135 complex elements, \c{CE_} for control elements, and \c{PE_} for
136 primitive elements. We will in the following three sections see what
137 defines the different elements and see examples of widgets that use
140 The QStyle class description contains a list of these elements and
141 their roles in styling widgets. We will see how they are used when
142 we style individual widgets.
144 \section3 Primitive Elements
146 Primitive elements are GUI elements that are common and often used
147 by several widgets. Examples of these are frames, button bevels,
148 and arrows for spin boxes, scroll bars, and combo boxes.
149 Primitive elements cannot exist on their own: they are always part
150 of a larger construct. They take no part in the interaction with
151 the user, but are passive decorations in the GUI.
153 \section3 Control Elements
155 A control element performs an action or displays information
156 to the user. Examples of control elements are push buttons, check
157 boxes, and header sections in tables and tree views. Control
158 elements are not necessarily complete widgets such as push
159 buttons, but can also be widget parts such as tab bar tabs and
160 scroll bar sliders. They differ from primitive elements in that
161 they are not passive, but fill a function in the interaction with
162 the user. Controls that consist of several elements often use the
163 style to calculate the bounding rectangles of the elements. The
164 available sub elements are defined by the \l{QStyle::}{SubElement}
165 enum. This enum is only used for calculating bounding rectangles;
166 sub elements are not graphical elements to be drawn like primitive,
167 control, and complex elements.
169 \section3 Complex Control Elements
171 Complex control elements contain sub controls. Complex controls
172 behave differently depending on where the user handles them with
173 the mouse and which keyboard keys are pressed. This is dependent
174 on which sub control (if any) the mouse is over or pressed on.
175 Examples of complex controls are scroll bars and
176 combo boxes. With a scroll bar, you can use the mouse to move the
177 slider and press the line up and line down buttons. The available
178 sub controls are defined by the \l{QStyle}{SubControl} enum.
180 In addition to drawing, the style needs to provide the widgets
181 with information on which sub control (if any) a mouse press was
182 made on. For instance, a QScrollBar needs to know if the user
183 pressed the slider, the slider groove, or one of the buttons.
185 Note that sub controls are not the same as the control elements
186 described in the previous section. You cannot use the style to
187 draw a sub control; the style will only calculate the bounding
188 rectangle in which the sub control should be drawn. It is common,
189 though, that complex elements use control and primitive elements
190 to draw their sub controls, which is an approach that is
191 frequently used by the built-in styles in Qt and also the Java
192 style. For instance, the Java style uses PE_IndicatorCheckBox to
193 draw the check box in group boxes (which is a sub control of
194 \c CC_GroupBox). Some sub controls have an equivalent control element,
195 e.g., the scroll bar slider (\c SC_SCrollBarSlider and
196 \c CE_ScrollBarSlider).
198 \section3 Other QStyle Tasks
200 The style elements and widgets, as mentioned, use the style to
201 calculate bounding rectangles of sub elements and sub controls.
202 Pixel metrics, which are style-dependent sizes in screen
203 pixels, are also used for measurements when drawing. The available
204 rectangles and pixel metrics are represented by three enums in
205 QStyle: \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and
206 \l{QStyle::}{PixelMetric}. Values of the enums can easily by
207 identified as they start with SE_, SC_ and PM_.
209 The style also contains a set of style hints, which is
210 represented as values in the \l{QStyle::}{StyleHint} enum. All
211 widgets do not have the same functionality and look in the
212 different styles. For instance, when the menu items in a menu do not
213 fit in a single column on the screen, some styles support
214 scrolling while others draw more than one column to fit all items.
216 A style usually has a set of standard images (such as a warning, a
217 question, and an error image) for message boxes, file dialogs,
218 etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its
219 values represent the standard images. Qt's widgets use these, so
220 when you implement a custom style you should supply the images
221 used by the style that is being implemented.
223 The style calculates the spacing between widgets in layouts. There
224 are two ways the style can handle these calculations. You can set
225 the \c PM_LayoutHorizontalSpacing and \c PM_LayoutVerticalSpacing, which
226 is the way the Java style does it (through QCommonStyle).
227 Alternatively, you can implement QStyle::layoutSpacing() and
228 QStyle::layoutSpacingImplementation() if you need more control over
229 this part of the layout. In these functions you can calculate the
230 spacing based on control types (QSizePolicy::ControlType) for
231 different size policies (QSizePolicy::Policy) and also the style
232 option for the widget in question.
234 \section2 Style Options
236 The sub-classes of QStyleOption contain all information necessary
237 to style the individual elements. Style options are instantiated -
238 usually on the stack - and filled out by the caller of the QStyle
239 function. Depending on what is drawn the style will expect
240 different a different style option class. For example, the
241 \c QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect
242 argument, and it's possible to create custom subclasses that a
243 custom style can use. The style options keep public variables
244 for performance reasons.
246 The widgets can be in a number of different states, which are
247 defined by the \l{QStyle::}{State} enum. Some of the state flags have
248 different meanings depending on the widget, but others are common
249 for all widgets like \c State_Disabled. It is QStyleOption that sets
250 the common states with QStyleOption::initFrom(); the rest of the
251 states are set by the individual widgets.
253 Most notably, the style options contain the palette and bounding
254 rectangles of the widgets to be drawn. Most widgets have
255 specialized style options. QPushButton and QCheckBox, for
256 instance, use QStyleOptionButton as their style option, which contains
257 the text, icon, and the size of their icon. The exact contents of
258 all options are described when we go through the individual widgets.
260 When reimplementing QStyle functions that take a
261 QStyleOption parameter, you often need to cast the
262 QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For
263 safety, you can use qstyleoption_cast() to ensure that the
264 pointer type is correct. If the object isn't of the right type,
265 qstyleoption_cast() returns \nullptr. For example:
267 \snippet code/doc_src_qt4-styles.cpp 0
269 The following code snippet illustrates how to use QStyle to
270 draw the focus rectangle from a custom widget's paintEvent():
272 \snippet code/doc_src_qt4-styles.cpp 1
274 The next example shows how to derive from an existing style to
275 customize the look of a graphical element:
277 \snippet customstyle/customstyle.h 0
279 \snippet customstyle/customstyle.cpp 2
280 \snippet customstyle/customstyle.cpp 3
281 \snippet customstyle/customstyle.cpp 4
283 \section2 QStyle Functions
285 The QStyle class defines three functions for drawing the primitive,
286 control, and complex elements:
287 \l{QStyle::}{drawPrimitive()},
288 \l{QStyle::}{drawControl()}, and
289 \l{QStyle::}{drawComplexControl()}. The functions takes the
290 following parameters:
293 \li the enum value of the element to draw.
294 \li a QStyleOption which contains the information needed to
296 \li a QPainter with which to draw the element.
297 \li a pointer to a QWidget, typically the widget
298 that the element is painted on.
301 Not all widgets send a pointer to themselves. If the style
302 option sent to the function does not contain the information you
303 need, you should check the widget implementation to see if it
304 sends a pointer to itself.
306 The QStyle class also provides helper functions that are used
307 when drawing the elements. The \l{QStyle::}{drawItemText()}
308 function draws text within a specified rectangle, taking a
309 QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()}
310 function helps to align a pixmap within a specified bounding
313 Other QStyle functions do various calculations for the
314 functions that do drawing. The widgets also use these functions for
315 calculating size hints and bounding rectangles if they draw several
316 style elements themselves. As with the functions that draw elements,
317 the helper functions typically take the same arguments.
320 \li The \l{QStyle::}{subElementRect()} function takes a
321 \l{QStyle::}{SubElement} enum value and calculates a bounding
322 rectangle for a sub element. The style uses this function to
323 know where to draw the different parts of an element. This is
324 mainly done for reuse; if you create a new style, you can use
325 the same location of sub elements as the super class.
327 \li The \l{QStyle::}{subControlRect()} function is used to
328 calculate bounding rectangles for sub controls in complex
329 controls. When you implement a new style, you reimplement \c
330 subControlRect() and calculate the rectangles that are different
331 from the super class.
333 \li The \l{QStyle::}{pixelMetric()} function returns a pixel
334 metric, which is a style-dependent size given in screen
335 pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum
336 and returns the correct measurement. Note that pixel metrics do
337 not necessarily have to be static measurements, but can be
338 calculated with, for example, the style option.
340 \li The \l{QStyle::}{hitTestComplexControl()} function returns the
341 sub control that the mouse pointer is over in a complex control.
342 Usually, this is simply a matter of using
343 \l{QStyle::}{subControlRect()} to get the bounding rectangles of
344 the sub controls, and then seeing which rectangle contains the
345 position of the cursor.
348 QStyle also has the functions \l{QStyle::}{polish()} and
349 \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish()
350 function before being shown and to \c unpolish() when they
351 are hidden. You can use these functions to set attributes on the
352 widgets or do other work that is required by your style. For
353 instance, if you need to know when the mouse is hovering over the
354 widget, you need to set the \l{Qt::}{WA_Hover} widget attribute.
355 The \c State_MouseOver state flag will then be set in the widget's
358 QStyle has a few static helper functions that do some common and
359 difficult tasks. They can calculate the position of a slider
360 handle from the value of the slider and transform rectangles
361 and draw text considering reverse layouts; see the QStyle
362 class documentation for more details.
364 The usual approach when one reimplements QStyle virtual
365 functions is to do work on elements that are different from the
366 super class; for all other elements, you can simply use the super
367 class implementation.
369 \section2 The Palette
371 Each style provides a color - that is, QBrush - palette that
372 should be used for drawing the widgets. There is one set of colors
373 for the different widget states (QPalette::ColorGroup): active
374 (widgets in the window that have keyboard focus), inactive (widgets
375 used for other windows), and disabled (widgets that are disabled).
376 The states can be found by querying the \c State_Active
377 and \c State_Enabled state flags. Each set contains certain color
378 roles given by the QPalette::ColorRole enum. The roles describe in
379 which situations the colors should be used (e.g., for painting
380 widget backgrounds, text, or buttons).
382 How the color roles are used is up to the style. For instance, if
383 the style uses gradients, one can use a palette color and make it
384 darker or lighter with QColor::darker() and QColor::lighter() to
385 create the gradient. In general, if you need a brush that is not
386 provided by the palette, you should try to derive it from one.
388 QPalette, which provides the palette, stores colors for
389 different widget states and color roles. The palette for a style
390 is returned by \l{QStyle::}{standardPalette()}. The standard
391 palette is not installed automatically when a new style is set
392 on the application (QApplication::setStyle()) or widget
393 (QWidget::setStyle()), so you must set the palette yourself
394 with (QApplication::setPalette()) or (QWidget::setPalette()).
396 It is not recommended to hard-code colors, as applications and
397 individual widgets can set their own palette and also use their
398 style's palette for drawing. Note that none of Qt's widgets set
399 their own palette. The Java style does hard-code some colors, but
400 only as a decision of the author; it is not advised. Of course,
401 it is not intended that the style should look good with any palette.
403 \section2 Implementation Issues
405 When you implement styles, there are several issues to
406 consider. We will give some hints and advice on implementation
409 When implementing styles, it is necessary to look through the
410 code of the widgets and code of the base class and its ancestors.
411 This is because the widgets use the style differently, because the
412 implementation in the different styles' virtual functions can
413 affect the state of the drawing (e.g., by altering the QPainter
414 state without restoring it and drawing some elements without using
415 the appropriate pixel metrics and sub elements).
417 It is recommended that the styles do not alter the proposed size
418 of widgets with the QStyle::sizeFromContents() function, but let
419 the QCommonStyle implementation handle it instead. If changes need
420 to be made, you should try to keep them small; application development
421 may be difficult if the layout of widgets looks considerably
422 different in the various styles.
426 We have implemented a style that resembles the Java default look
427 and feel (previously known as Metal). We have done this as it is
428 relatively simple to implement and we wanted to build a style for
429 this overview document. To keep it simple and not too extensive, we
430 have simplified the style somewhat, but Qt is perfectly able to
431 make an exact copy of the style. However, there are no concrete
432 plans to implement the style as a part of Qt.
434 In this section we will have a look at some implementation
435 issues. Finally, we will see a complete example on the styling of
436 a Java widget. We will continue to use the Java style
437 throughout the document for examples and widget images. The
438 implementation itself is somewhat involved, and it is not
439 intended that you should read through it.
441 \section2 Design and Implementation
443 The first step in designing the style was to select the base
444 class. We chose to subclass QCommonStyle. This class implements
445 most of the functionality we need, other than performing the actual
448 The style is implemented in one class. We have done this
449 because we find it convenient to keep all code in one file. Also,
450 it is an advantage with regards to optimization as we instantiate
451 less objects. We also keep the number of functions at a minimum by
452 using switches to identify which element to draw in the functions.
453 This results in large functions, but since we divide the code for
454 each element in the switches, the code should still be easy to
457 \section2 Limitations and Differences from Java
459 We have not fully implemented every element in the Java style.
460 This way, we have reduced the amount and complexity of the code.
461 In general, the style was intended as a practical example for
462 this style overview document, and not to be a part of Qt
465 Not all widgets have every state implemented. This goes for
466 states that are common, e.g., \c State_Disabled. Each state is,
467 however, implemented for at least one widget.
469 We have only implemented ticks below the slider. Flat push
470 buttons are also left out. We do not handle the case where the
471 title bars and dock window titles grow too small for their
472 contents, but simply draw sub controls over each other.
474 We have not tried to emulate the Java fonts. Java and Qt use very
475 different font engines, so we don't consider it worth the effort
476 as we only use the style as an example for this overview.
478 We have hard-coded the colors (we don't use the QPalette) for
479 the linear gradients, which are used, for example, for button
480 bevels, tool bars, and check boxes. This is because the Java
481 palette cannot produce these colors. Java does not change these
482 colors based on widget color group or role anyway (they are not
483 dependent on the palette), so it does not present a problem in any
486 It is Qt's widgets that are styled. Some widgets do not exist
487 at all in Java, e.g., QToolBox. Others contain elements that the
488 Java widgets don't. The tree widget is an example of the latter in
489 which Java's JTree does not have a header.
491 The style does not handle reverse layouts. We assume that the
492 layout direction is left to right. QCommonStyle handles reverse
493 widgets; if we implemented reverse layouts, widgets that we change
494 the position of sub elements, or handle text alignment in labels
495 ourselves would need to be updated.
497 \section2 Styling Java Check Boxes
499 As an example, we will examine the styling of check boxes in the
500 Java style. We describe the complete process and print all code in
501 both the Java style and Qt classes involved. In the rest of this
502 document, we will not examine the source code of the individual
503 widgets. Hopefully, this will give you an idea on how to search
504 through the code if you need to check specific implementation
505 details; most widgets follow the same structure as the check
506 boxes. We have edited the QCommonStyle code somewhat to remove
507 code that is not directly relevant for check box styling.
509 We start with a look at how QCheckBox builds its style option,
510 which is QStyleOptionButton for checkboxes:
512 \snippet code/doc_src_styles.cpp 0
514 First we let QStyleOption set up the option with the information
515 that is common for all widgets with \c initFrom(). We will look at
518 QStyleOption's \c down variable is \c true when the user presses the box down;
519 this is true of the checkbox whether the box is checked or not. The
520 \c State_NoChange state is set when we have a tri-state checkbox and
521 it is partially checked. It has \c State_On if the box is checked and
522 \c State_Off if it is unchecked. \c State_MouseOver is set if the mouse
523 hovers over the checkbox and the widget has attribute \c Qt::WA_Hover
524 set - you set this in QStyle::polish(). In addition, the style
525 option also contains the text, icon, and icon size of the button.
527 \l{QStyleOption::}{initFrom()} sets up the style option with the
528 attributes that are common for all widgets. We print its
531 \snippet code/doc_src_styles.cpp 1
533 The \c State_Enabled is set when the widget is enabled. When the
534 widget has focus the \c State_HasFocus flag is set. Equally, the
535 \c State_Active flag is set when the widget is a child of the active
536 window. The \c State_MouseOver will only be set if the widget has
537 the \c WA_HoverEnabled windows flag set. Notice that keypad
538 navigation must be enabled in Qt for the \c State_HasEditFocus to
539 be included; it is not included by default.
541 In addition to setting state flags the QStyleOption contains
542 other information about the widget: \c direction is the layout
543 direction of the layout, \c rect is the bounding rectangle of the
544 widget (the area in which to draw), \c palette is the QPalette
545 that should be used for drawing the widget, and \c fontMetrics is
546 the metrics of the font that is used by the widget.
548 We give an image of a checkbox and the style option to match
551 \image javastyle/checkboxexample.png A Java style checkbox
553 The above checkbox will have the following state flags in its
564 \li \c State_NoChange
573 \li \c State_MouseOver
579 \li \c State_HasFocus
582 \li \c State_KeyboardFocusChange
589 The QCheckBox paints itself in QWidget::paintEvent() with
590 style option \c opt and QStylePainter \c p. The QStylePainter
591 class is a convenience class to draw style elements. Most
592 notably, it wraps the methods in QStyle used for painting. The
593 QCheckBox draws itself as follows:
595 \snippet code/doc_src_styles.cpp 2
597 QCommonStyle handles the CE_CheckBox element. The QCheckBox
598 has two sub elements: SE_CheckBoxIndicator (the checked indicator)
599 and SE_CheckBoxContents (the contents, which are used for the
600 checkbox label). QCommonStyle also implements these sub element
601 bounding rectangles. Next, we'll have a look at the QCommonStyle code:
603 \snippet code/doc_src_styles.cpp 3
605 As can be seen from the code extract, the common style gets
606 the bounding rectangles of the two sub elements of
607 CE_CheckBox, and then draws them. If the checkbox has focus,
608 the focus frame is also drawn.
610 The Java style draws CE_CheckBoxIndicator, while QCommonStyle
611 handles CE_CheckboxLabel. We will examine each implementation and
612 start with CE_CheckBoxLabel:
614 \snippet code/doc_src_styles.cpp 4
616 \l{QStyle::}{visualAlignment()} adjusts the alignment of text
617 according to the layout direction. We then draw an icon if it
618 exists, and adjust the space left for the text.
619 \l{QStyle::}{drawItemText()} draws the text, taking alignment,
620 layout direction, and the mnemonic into account. It also uses the
621 palette to draw the text in the right color.
623 The drawing of labels often gets somewhat involved. Luckily, it
624 can usually be handled by the base class. The Java style
625 implements its own push button label, since Java centers button
626 contents also when the button has an icon. You can examine that
627 implementation if you need an example of reimplementing label
630 We'll now take a look at the Java implementation
631 of CE_CheckBoxIndicator in \c drawControl():
633 \snippet javastyle.cpp 0
635 We first save the state of the painter. This is not always
636 necessary, but in this case the QCommonStyle needs the painter in
637 the same state as it was when PE_IndicatorCheckBox was called (We
638 could also set the state with function calls, of course). We then
639 use \c drawButtonBackground() to draw the background of the check
640 box indicator. This is a helper function that draws the background
641 and also the frame of push buttons and check boxes. We take a look
642 at that function below. We then check if the mouse is hovering
643 over the checkbox. If it is, we draw the frame that Java checkboxes
644 have when the box is not pressed down and the mouse is over it.
645 You may note that Java does not handle tri-state boxes, so we have
648 Here we use a PNG image for our indicator. We could also check
649 if the widget is disabled. We would then have to use
650 another image with the indicator in the disabled color.
652 \snippet javastyle.cpp 1
654 We have seen how check boxes are styled in the Java style from the
655 time the widget gets a paint request to the time the style is
656 finished painting. To learn in detail how each widget is painted,
657 you need to go through the code step-by-step as we have done here.
658 However, it is usually enough to know which style elements the
659 widgets draw. The widget builds a style option and calls on the
660 style one or more times to draw the style elements of which it
661 consists. Usually, it is also sufficient to know the states a widget
662 can be in and the other contents of the style option, i.e., what we
663 list in the next section.
665 \section1 Widget Walkthrough
667 In this section, we will examine how most of Qt's widgets are
668 styled. Hopefully, this will save you some time and effort while
669 developing your own styles and widgets. You will not find
670 information here that is not attainable elsewhere (i.e., by
671 examining the source code or the class descriptions for the style
674 We mostly use Java style widgets as examples. The Java style does not
675 draw every element in the element trees. This is because they are
676 not visible for that widget in the Java style. We still make sure
677 that all elements are implemented in a way that conforms with the
678 Java style, as custom widgets might need them (this does not
679 exclude leaving implementations to QCommonStyle though).
681 The following is given for each widget:
684 \li A table with the members (variables, etc.) of its style option.
685 \li A table of the state flags (QStyle::StateFlag) that
686 can be set on the widget and when the states are set.
687 \li Its element tree (see section \l{The Style Elements}).
688 \li An image of the widget in which the elements are outlined.
689 \omit This is not written yet - probably never will be
691 \li A list of style hints that should be checked for the
693 \li A list of standard pixmaps that could be used by the
698 The element tree contains the primitive, control, and complex
699 style elements. By doing a top-down traversal of the element tree,
700 you get the sequence in which the elements should be drawn. In the
701 nodes, we have written the sub element rectangles, sub control
702 elements, and pixel metrics that should be considered when drawing
703 the element of the node.
705 Our approach on styling centers on the drawing of the widgets. The
706 calculations of sub elements rectangles, sub controls, and pixel
707 metrics used \b during drawing is only listed as contents in
708 the element trees. Note that there are rectangles and pixel
709 metrics that are only used by widgets. This leaves these
710 calculations untreated in the walkthrough. For instance, the
711 \l{QStyle::}{subControlRect()} and
712 \l{QStyle::}{sizeFromContents()} functions often call
713 \l{QStyle::}{subElementRect()} to calculate their bounding
714 rectangles. We could draw trees for this as well. However, how
715 these calculations are done is completely up to the individual
716 styles, and they do not have to follow a specific structure (Qt
717 does not impose a specific structure). You should still make sure
718 that you use the appropriate pixel metrics, though. To limit the
719 size of the document, we have therefore chosen not to include
720 trees or describe the calculations made by the Java (or any other)
723 You may be confused about how the different pixel metrics, sub
724 element rectangles, and sub control rectangles should be used when
725 examining the trees. If you are in doubt after reading the QStyle
726 enum descriptions, we suggest that you examine the QCommonStyle
729 Some of the bounding rectangles that we outline in the widget
730 images are equal. Reasons for this are that some elements draw
731 backgrounds while others draw frames and labels. If in doubt,
732 check the description of each element in QStyle. Also, some
733 elements are there to layout, i.e., decide where to draw, other
736 \section2 Common Widget Properties
738 Some states and variables are common for all widgets. These are
739 set with QStyleOption::initFrom(). Not all elements use this function;
740 it is the widgets that create the style options, and for some
741 elements the information from \l{QStyleOption::}{initFrom()} is not
744 A table with the common states follows:
752 \li Set if the widget is not disabled (see
753 QWidget::setEnabled())
756 \li Set if the widget has focus (see
759 \li \c State_KeyboardFocusChange
760 \li Set when the user changes focus with the keyboard
761 (see Qt::WA_KeyboardFocusChange)
763 \li \c State_MouseOver
764 \li Set if the mouse cursor is over the widget
767 \li Set if the widget is a child of the active window.
769 \li \c State_HasEditFocus
770 \li Set if the widget has the edit focus
773 The other common members for widgets are:
781 \li The bounding rectangle of the element to draw. This
782 is set to the widget bounding rectangle
786 \li The layout direction; a value of the
787 Qt::LayoutDirection enum.
790 \li The QPalette to use when drawing the element. This
791 is set to the widgets palette (QWidget::palette()).
794 \li The QFontMetrics to use when drawing text on the
798 The complex style options (classes that inherit
799 QStyleOptionComplex) used for complex style elements share two
800 variables: \l{QStyleOptionComplex::}{subControls} and
801 \l{QStyleOptionComplex::}{activeSubControls}. Both variables are
802 an OR'ed combination of QStyle::SubControl enum values. They
803 indicate which sub controls the complex control consists of and
804 which of these controls are currently active.
806 As mentioned, the style calculates the size of the widget's
807 contents, which the widgets calculate their size hints from. In
808 addition, complex controls also use the style to test which
809 sub-controls the mouse is over.
811 \section2 Widget Reference
813 Without further delay, we present the widget walkthrough; each
814 widget has its own sub-section.
816 \section3 Push Buttons
818 The style structure for push buttons is shown below. By doing a
819 top-down traversal of the tree, you get the sequence in which the
820 elements should be drawn.
822 \image javastyle/pushbutton.png The style structure for push buttons
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).
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
840 \image javastyle/button.png
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.
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:
858 \li Button is down or menu is pressed shown
861 \li Button is checked
864 \li Button is not flat and not pressed down
867 Other members of QStyleOptionButton are:
875 \li Flags of the QStyleOptionButton::ButtonFeatures enum,
876 which describes various button properties (see enum)
879 \li The buttons QIcon (if any)
882 \li The QSize of the icon
885 \li a QString with the buttons text
888 \section3 Check and Radio Buttons
890 The structures for radio and check buttons are identical.
891 We show the structure using QCheckBox element and pixel
894 \image javastyle/checkbox.png
896 QStyleOptionButton is used as the style option for both check
897 and radio buttons. We first give a table of the states that
898 can be set in the option:
906 \li The box is pressed down
908 \li \c State_NoChange
909 \li The box is partially checked (for tri-state
913 \li The box is checked
916 \li The box is unchecked
919 See \l{Push Buttons} for a table over other members in the
920 QStyleOptionButton class.
924 In Qt, QTabBar uses the style to draw its tabs. Tabs exist either
925 in a QTabWidget, which contains a QTabBar, or as a separate bar.
926 If the bar is not part of a tab widget, it draws its own base.
928 QTabBar lays out the tabs, so the style does not have control over
929 tab placement. However, while laying out its tabs, the bar asks
930 the style for \c PM_TabBarTabHSpace and \c PM_TabBarTabVSpace, which is
931 extra width and height over the minimum size of the tab bar tab
932 label (icon and text). The style can also further influence the
933 tab size before it is laid out, as the tab bar asks for
934 \c CT_TabBarTab. The bounding rectangle of the bar is decided by the
935 tab widget when it is part of the widget (still considering
938 The tab bar is responsible for drawing the buttons that appear on
939 the tab bar when all tabs do not fit. Their placement is not
940 controlled by the style, but the buttons are \l{QToolButton}s
941 and are therefore drawn by the style.
943 Here is the style structure for QTabWidget and QTabBar:
945 \image javastyle/tab.png
947 The dotted lines indicate that the QTabWidget contains a tab bar,
948 but does not draw the tab bar itself. QTabBar only draws its base line
949 when not part of a tab widget, and it keeps two tool
950 buttons that scroll the bar when all tabs do not fit; see \l{Tool
951 Buttons} for their element tree. Also note that since the buttons
952 are children of the tab bar, they are drawn after the bar. The
953 tabs' bounding rectangles overlap the base by \c PM_TabBarBaseOverlap.
955 Here is a tab widget in the Java style:
957 \image javastyle/tabwidget.png
959 In the Java style, the tab bar shape and label have the same bounding
960 rectangle as \c CE_TabBarTab. Notice that the tabs overlap with the
961 tab widget frame. The base of the tab bar (if drawn) is the area where
962 the tabs and frame overlap.
964 The style option for tabs (QStyleOptionTab) contains the necessary
965 information for drawing tabs. The option contains the position of
966 the tab in the tab bar, the position of the selected tab, the
967 shape of the tab, the text, the icon, and the icon's size.
969 As the Java style tabs don't overlap, we also present an image of
970 a tab widget in the common style. Note that if you want the tabs
971 to overlap horizontally, you do that when drawing the tabs in
972 \c CE_TabBarTabShape; the tabs bounding rectangles will not be
973 altered by the tab bar. The tabs are drawn from left to right in a
974 north tab bar shape, top to bottom in an east tab bar shape, etc.
975 The selected tab is drawn last, so that it is easy to draw it over
976 the other tabs (if it is to be bigger).
978 \image javastyle/windowstabimage.png
980 A table of the states a tab bar can set on its tabs follows:
988 \li The tab is pressed on with the mouse.
990 \li \c State_Selected
991 \li If it is the current tab.
993 \li \c State_HasFocus
994 \li The tab bar has focus and the tab is selected.
997 Note that individual tabs may be disabled even if the tab bar
998 is not. The tab will be active if the tab bar is active.
1000 Here follows a table of QStyleOptionTab's members:
1008 \li Flags of the CornerWidget enum, which indicate
1009 if and which corner widgets the tab bar has.
1012 \li The QIcon of the tab.
1015 \li The QSize of the icon.
1018 \li A TabPosition enum value that indicates the tab's
1019 position on the bar relative to the other tabs.
1022 \li Holds which row the tab is in.
1024 \li selectedPosition
1025 \li A value of the SelectedPosition enum that indicates
1026 whether the selected tab is adjacent to or is the
1030 \li A value of the QTabBar::Shape enum indicating
1031 whether the tab has rounded or triangular corners
1032 and the orientation of the tab.
1038 The frame for tab widgets use QStyleOptionTabWidgetFrame as
1039 style option. We list its members here. It does not have
1040 states set besides the common flags.
1047 \li leftCornerWidgetSize
1048 \li The QSize of the left corner widget (if any).
1050 \li rightCornerWidgetSize
1051 \li The QSize of the right corner widget (if any).
1054 \li Holds the line with for drawing the panel.
1057 \li This value is currently always 0.
1060 \li The shape of the tabs on the tab bar.
1063 \li The QSize of the tab bar.
1066 \section3 Scroll Bars
1068 Here is the style structure for scrollbars:
1070 \image javastyle/scrollbar.png
1072 QScrollBar simply creates its style option and then draws
1073 \c CC_ScrollBar. Some styles draw the background of add page and sub
1074 page with \c PE_PanelButtonBevel, and also use indicator arrows to
1075 draw the arrows in the next and previous line indicators; we have
1076 not included these in the tree as their use is up to the
1077 individual style. The style's \c PM_MaximumDragDistance is the
1078 maximum distance in pixels the mouse can move from the bounds
1079 of the scroll bar and still move the handle.
1081 Here is an image of a scrollbar in the Java style:
1083 \image javastyle/scrollbarimage.png
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.
1092 We have a look at the different states a scroll bar can set on
1100 \li \c State_Horizontal
1101 \li The scroll bar is horizontal.
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.
1115 \li The maximum value of the scroll bar.
1118 \li The minimum value of the scroll bar.
1121 \li The number of pixels between notches.
1124 \li A value of the Qt::Orientation enum that specifies
1125 whether the scroll bar is vertical or horizontal.
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.
1133 \li The number by which to increase or decrease the slider's
1134 value on single (or line) steps.
1137 \li The value of the slider.
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.
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.
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:
1161 \image javastyle/slider.png
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
1167 \image javastyle/sliderimage.png
1169 QSlider uses QStyleOptionSlider as all \l{QAbstractSlider}s do. We
1170 present a table with the members that affect QSlider:
1178 \li The maximum value of the slider.
1181 \li The minimum value of the slider.
1184 \li This is the number of pixels between each notch.
1187 \li A Qt::Orientation enum value that indicates whether the
1188 slider is vertical or horizontal.
1191 \li The number by which to increase or decrease the slider's
1192 value on page steps.
1195 \li The number by which to increase or decrease the slider's
1196 value on single (or line) steps.
1199 \li The value of the slider.
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.
1209 \li This member is used instead of QStyleOption::direction
1210 for all abstract sliders.
1213 You should note that the slider does not use direction for
1214 reverse layouts; it uses \c upsideDown.
1216 \section3 Spin Boxes
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.
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.
1228 \image javastyle/spinbox.png
1230 \image javastyle/spinboximage.png
1232 The QStyleOptionSpinBox, which is the style option for spin
1233 boxes. It can set the following states on the spin box:
1241 \li Is set if one of the sub controls \c CC_SpinUp or
1242 \c CC_SpinDown is pressed on with the mouse.
1245 The rest of the members in the spin box style options are:
1253 \li Boolean that is \c true if the spin box is to draw a
1257 \li Value of the ButtonSymbols enum that decides the
1258 symbol on the up/down buttons.
1261 \li A value of the StepEnabled enum, indicating which of the
1262 spin box buttons are pressed down.
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.
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
1278 \image javastyle/titlebar.png
1280 In an image over a title bar in the Java style, we show the
1281 bounding rectangles of the sub elements supported by the Java style
1282 (all of which are drawn with standard pixmaps). It is usual to
1283 draw the button backgrounds using \c PE_PanelButtonTool, but it's not
1286 \image javastyle/titlebarimage.png
1288 The style option for title bars is QStyleOptionTitleBar. Its
1297 \li The title bar's icon.
1300 \li The text for the title bar's label.
1303 \li Flags of the Qt::WindowFlag enum. The window flags
1304 used by QMdiArea for window management.
1307 \li This is the QWidget::windowState() of the window
1308 that contains the title bar.
1313 A QComboBox uses the style to draw the button and label of
1314 non-editable boxes with \c CC_ComboBox and \c CE_ComboBoxLabel.
1316 The list that pops up when the user clicks on the combo box is
1317 drawn by a \l{Delegate Classes}{delegate}, which we do not cover
1318 in this overview. You can, however, use the style to control the
1319 list's size and position with the sub element
1320 \c SC_ComboBoxListBoxPopup. The style also decides where the edit
1321 field for editable boxes should be with \c SC_ComboBoxEditField; the
1322 field itself is a QLineEdit that is a child of the combo box.
1324 \image javastyle/combobox.png
1326 We show an image over a Java style combo box in which we have
1327 outlined its sub elements and sub element rectangles:
1329 \image javastyle/comboboximage.png
1331 Java combo boxes do not use the focus rect; it changes its
1332 background color when it has focus. The \c SC_ComboBoxEdit field is
1333 used both by QComboBox to calculate the size of the edit field and
1334 the style for calculating the size of the combo box label.
1336 The style option for combo boxes is QStyleOptionComboBox. It
1337 can set the following states:
1344 \li \c State_Selected
1345 \li The box is not editable and has focus.
1348 \li \c SC_ComboBoxArrow is active.
1351 \li The container (list) of the box is visible.
1354 The style options other members are:
1362 \li The icon of the current (selected) item of the
1366 \li The text of the current item in the box.
1369 \li Holds whether the combo box is editable or not.
1372 \li Holds whether the combo box has a frame or not.
1375 \li The size of the current items icon.
1378 \li The bounding rectangle of the combo box's popup
1382 \section3 Group Boxes
1384 When calculating the size hint, QGroupBox fetches three pixel
1385 metrics from the style: \c PM_IndicatorWidth,
1386 \c PM_CheckBoxLabelSpacing, and \c PM_IndicatorHeight. QGroupBox has
1387 the following style element tree:
1389 \image javastyle/groupbox.png
1391 Qt does not impose restrictions on how the check box is drawn; the
1392 Java style draws it with \c CE_IndicatorCheckBox. See \l{Check and
1393 Radio Buttons} for the complete tree.
1395 We also give an image of the widget with the sub controls and
1396 sub control rectangles drawn:
1398 \image javastyle/groupboximage.png
1400 The style option for group boxes is QStyleOptionGroupBox. The
1401 following states can be set on it:
1409 \li The check box is checked.
1412 \li The check box is pressed down.
1415 \li The check box is unchecked (or there is no check box).
1418 The remaining members of QStyleOptionGroupBox are:
1426 \li Flags of the QStyleOptionFrame::FrameFeatures
1427 enum describing the frame of the group box.
1430 \li The line width with which to draw the panel. This
1434 \li The text of the group box.
1437 \li The alignment of the group box title.
1440 \li The QColor of the text.
1445 As the structure of splitters are simple and do not contain any
1446 sub elements, we do not include any images of splitters. \c CE_Splitter
1447 does not use any other elements or metrics.
1449 For its style option, the splitter uses the base class QStyleOption.
1450 It can set the following state flags on it:
1457 \li \c State_Horizontal
1458 \li Set if it is a horizontal splitter.
1461 QSplitter does not use \l{QStyleOption::}{initFrom()} to set up its
1462 option; it sets the \c State_MouseOver and \c State_Disabled flags
1465 \section3 Progress Bar
1467 The \c CE_ProgressBar element is used by QProgressBar, and it is the
1468 only element used by this widget. We start with the style structure:
1470 \image javastyle/progressbar.png
1472 Here is a progress bar in the common style (the Java style
1473 bounding rectangles are equal):
1475 \image javastyle/progressbarimage.png
1477 The style option for QProgressBar is QStyleOptionProgressBar.
1478 The bar does not set any state flags, but the other members of the
1487 \li The minimum value of the bar.
1490 \li The maximum value of the bar.
1493 \li The current value of the bar.
1496 \li How the text is aligned in the label.
1499 \li Whether the label is drawn.
1505 \li Progress bars can be vertical or horizontal.
1507 \li invertedAppearance
1508 \li The progress is inverted (i.e., right to left in a
1512 \li Boolean, that, if \c true, turns the label of vertical
1513 progress bars 90 degrees.
1516 \section3 Tool Buttons
1518 Tool buttons exist either independently or as part of tool bars.
1519 They are drawn equally either way. The QToolButton draws only one
1520 style element: \c CC_ToolButton.
1522 Below is a tree of the widget's style structure:
1524 \image javastyle/toolbutton.png
1526 Note that \c PE_FrameButtonTool and \c PE_IndicatorArrowDown are
1527 included in the tree as the Java style draws them, but they can
1528 safely be omitted if you prefer it. The structure may also be
1529 different. QCommonStyle, for instance, draws both
1530 \c PE_IndicatorButtonDropDown and \c PE_IndicatorArrowDown in
1533 We also have an image of a tool button where we have outlined
1534 the sub element bounding rectangles and sub controls.
1536 \image javastyle/toolbuttonimage.png
1538 Here is the states table for tool buttons:
1545 \li \c State_AutoRise
1546 \li The tool button has the autoRise property set.
1549 \li The button is not sunken (i.e., by being checked or
1550 pressed on with the mouse).
1553 \li The button is down.
1556 \li The button is checkable and checked.
1559 QStyleOptionToolButton also contains the following members:
1567 \li A Qt::ArrowType enum value, which contains the
1568 direction of the buttons arrow (if an arrow is to
1569 be used in place of an icon).
1572 \li Flags of the QStyleOptionToolButton::ButtonFeature
1573 enum describing if the button has an arrow, a menu,
1574 and/or has a popup-delay.
1577 \li The QFont of the buttons label.
1580 \li The QIcon of the tool button.
1583 \li The icon size of the button's icon.
1586 \li The position of the button, as given by
1590 \li The text of the button.
1593 \li A Qt::ToolButtonStyle enum value which decides
1594 whether the button shows the icon, the text, or both.
1599 Toolbars are part of the \l{QMainWindow}{main window framework},
1600 and cooperate with the QMainWindow to which they belong while it
1601 builds its style option. A main window has 4 areas that toolbars
1602 can be placed in. They are positioned next to the four sides of
1603 the window (i.e., north, south, east and west). Within each area
1604 there can be more than one line of toolbars; a line consists of
1605 toolbars with equal orientation (vertical or horizontal) placed
1608 \l{QToolBar}{Toolbars} in Qt consist of three elements:
1609 \c CE_ToolBar, \c PE_IndicatorToolBarHandle, and
1610 \c PE_IndicatorToolBarSeparator. It is QMainWindowLayout that
1611 calculates the bounding rectangles (i.e., position and size of the
1612 toolbars and their contents. The main window also uses the \c
1613 sizeHint() of the items in the toolbars when calculating the size
1616 Here is the element tree for QToolBar:
1618 \image javastyle/toolbar.png
1620 The dotted lines indicate that the QToolBar keeps an instance of
1621 QToolBarLayout and that QToolBarSeparators are kept by
1622 QToolBarLayout. When the toolbar is floating (i.e., has its own
1623 window) the \c PE_FrameMenu element is drawn, else QToolBar draws
1626 Here is an image of a toolbar in the Java style:
1628 \image javastyle/toolbarimage.png
1630 QToolBarSaparator uses QStyleOption for its style option. It
1631 sets the \c State_Horizontal flag if the toolbar it lives in is
1632 horizontal. Other than that, they use \l{QStyleOption::}{initFrom()}.
1634 The style option for QToolBar is QStyleOptionToolBar. The only
1635 state flag set (besides the common flags) is \c State_Horizontal
1636 if the bar is horizontal (i.e., in the north or south toolbar area).
1637 The member variables of the style option are:
1645 \li Holds whether the bar is movable in a value of the
1646 ToolBarFeature, which is either Movable or None.
1649 \li The width of the tool bar frame.
1652 \li This variable is currently not used and is always 0.
1655 \li The position of the toolbar line within the toolbar
1656 area to which it belongs.
1658 \li positionWithinLine
1659 \li The position of the toolbar within the toolbar line.
1662 \li The toolbar area in which the toolbar lives.
1667 Menus in Qt are implemented in QMenu. The QMenu keeps a list of
1668 actions, which it draws as menu items. When QMenu receives paint
1669 events, it calculates the size of each menu item and draws them
1670 individually with \c CE_MenuItem. Menu items do not have a separate
1671 element for their label (contents), so all drawing is done in
1672 \c CE_MenuItem. The menu also draws the frame of the menu with
1673 \c PE_FrameMenu. It also draws \c CE_MenuScroller if the style supports
1674 scrolling. \c CE_MenuTearOff is drawn if the menu is too large for its
1677 In the style structure tree, we also include QMenu as it also does
1678 styling related work. The bounding rectangles of menu items are
1679 calculated for the menu's size hint and when the menu is displayed
1682 \image javastyle/menu.png
1684 The \c CE_MenuScroller and \c CE_MenuTearOff elements are handled by
1685 QCommonStyle and are not shown unless the menu is too large to fit
1686 on the screen. \c PE_FrameMenu is only drawn for pop-up menus.
1688 QMenu calculates rectangles based on its actions and calls
1689 \c CE_MenuItem and \c CE_MenuScroller if the style supports that.
1691 It is also usual to use \c PE_IndicatorCheckBox (instead of using
1692 \c PE_IndicatorMenuCheckMark) and \c PE_IndicatorRadioButton for drawing
1693 checkable menu items; we have not included them in the style tree
1694 as this is optional and varies from style to style.
1696 \image javastyle/menuimage.png
1698 The style option for menu items is QStyleOptionMenuItem. The
1699 following tables describe its state flags and other members.
1706 \li \c State_Selected
1707 \li The mouse is over the action and the action is not
1711 \li The mouse is pressed down on the menu item.
1713 \li \c State_DownArrow
1714 \li Set if the menu item is a menu scroller and it scrolls
1724 \li A value of the \l{QStyleOptionMenuItem::}{CheckType} enum,
1725 which is either NotCheckable, Exclusive, or
1729 \li Boolean that is \c true if the menu item is checked.
1732 \li The QFont to use for the menu item's text.
1735 \li The QIcon of the menu item.
1738 \li The maximum width allowed for the icon.
1740 \li menuHasCheckableItems
1741 \li Boolean which is \c true if at least one item in the
1745 \li The type of the menu item. This a value of the
1746 \l{QStyleOptionMenuItem::}{MenuItemType}.
1749 \li The bounding rectangle for the QMenu that the menu
1753 \li This is the distance between the text of the menu
1754 item and the shortcut.
1757 \li The text of the menu item.
1760 The setup of the style option for \c CE_MenuTearOff and
1761 \c CE_MenuScroller also uses QStyleOptionMenuItem; they only set the
1762 \c menuRect variable in addition to the common settings with
1763 QStyleOption's \l{QStyleOption::}{initFrom()}.
1767 QMenuBar uses the style to draw each menu bar item and the empty
1768 area of the menu bar. The pull-down menus themselves are
1769 \l{QMenu}s (see \l{Menus}). The style element tree for the menu
1772 \image javastyle/menubar.png
1774 The panel and empty area are drawn after the menu items. The
1775 QPainter that the QMenuBar sends to the style has the bounding
1776 rectangles of the items clipped out (i.e., clip region), so you
1777 don't need to worry about drawing over the items. The pixel
1778 metrics in QMenuBar are used when the bounding rectangles of the
1779 menu bar items are calculated.
1781 \image javastyle/menubarimage.png
1783 QStyleOptionMenuItem is used for menu bar items. The members that
1784 are used by QMenuBar are described in the following table:
1792 \li The bounding rectangle of the entire menu bar to
1793 which the item belongs.
1796 \li The text of the item.
1799 \li The icon of the menu item (it is not common that
1800 styles draw this icon).
1803 QStyleOptionMenuItem is also used for drawing \c CE_EmptyMenuBarArea.
1805 QStyleOptionFrame is used for drawing the panel frame. The
1806 \l{QStyleOptionFrame::}{lineWidth} is set to \c PM_MenuBarPanelWidth.
1807 The \l{QStyleOptionFrame::}{midLineWidth} is currently always set
1810 \section3 Item View Headers
1812 It is the style that draws the headers of Qt's item views. The
1813 item views keep the dimensions on individual sections. Also
1814 note that the delegates may use the style to paint decorations
1815 and frames around items. QItemDelegate, for instance, draws
1816 \c PE_FrameFocusRect and \c PE_IndicatorItemViewItemCheck.
1818 \image javastyle/header.png
1820 Here is a QTableWidget showing the bounding rects of a Java
1823 \image javastyle/headerimage.png
1825 The QHeaderView uses \c CT_HeaderSection, \c PM_HeaderMargin and
1826 \c PM_HeaderGripMargin for size and hit test calculations. The
1827 \c PM_HeaderMarkSize is currently not used by Qt. QTableView draws
1828 the button in the top-left corner (i.e., the area where the
1829 vertical and horizontal headers intersect) as a \c CE_Header.
1831 The style option for header views is QStyleOptionHeader. The view
1832 paints one header section at a time, so the data is for the
1833 section being drawn. Its contents are:
1841 \li The icon of the header (for section that is being drawn).
1844 \li The alignment (Qt::Alignment) of the icon in the header.
1847 \li A Qt::Orientation value deciding whether the header
1848 is the horizontal header above the view or the
1849 vertical header on the left.
1852 \li A QStyleOptionHeader::SectionPosition value
1853 giving the header section's position relative to
1857 \li Holds the section that is being drawn.
1859 \li selectedPosition
1860 \li A QStyleOptionHeader::SelectedPosition value giving
1861 the selected section's position relative to the
1862 section that is being painted.
1865 \li A QStyleOptionHeader::SortIndicator value that
1866 describes the direction in which the section's sort
1867 indicator should be drawn.
1870 \li The text of the currently drawn section.
1873 \li The Qt::Alignment of the text within the header section.
1876 \section3 Tree Branch Indicators
1878 The branch indicators in a tree view are drawn by the style with
1879 \c PE_IndicatorBranch. We think of indicators here as the indicators
1880 that describe the relationship of the nodes in the tree. The
1881 generic QStyleOption is sent to the style for drawing these
1882 elements. The various branch types are described by states. Since
1883 there is no specific style option, we simply present the states
1891 \li \c State_Sibling
1892 \li The node in the tree has a sibling (i.e., there is
1893 another node in the same column).
1896 \li This branch indicator has an item.
1898 \li \c State_Children
1899 \li The branch has children (i.e., a new sub-tree can
1900 be opened at the branch).
1903 \li The branch indicator has an opened sub-tree.
1906 The tree view (and tree widget) use the style to draw the branches
1907 (nodes) of the tree.
1909 QStyleOption is used as the style for \c PE_IndicatorBranch has state
1910 flags set depending on what type of branch it is.
1912 Since there is no tree structure for branch indicators, we only
1913 present an image of a tree in the Java style. Each state is marked
1914 in the image with a rectangle in a specific color (i.e., the
1915 rectangles are not bounding rectangles). All combinations of
1916 states you must be aware of are represented in the image.
1918 \image javastyle/branchindicatorimage.png
1920 \section3 Tool Boxes
1922 \c PM_SmallIconSize for sizeHints.
1924 QToolBox is a container that keeps a collection of widgets. It has
1925 one tab for each widget and displays one of them at a time. The
1926 tool box lays the components it displays (the tool box buttons
1927 and selected widget) in a QVBoxLayout. The style tree for tool
1928 boxes looks like this:
1930 \image javastyle/toolbox.png
1932 We show an image of a tool box in the Plastique style:
1934 \image javastyle/toolboximage.png
1936 All elements have the same bounding rectangles in the
1937 Plastique style as well as the other built-in Qt styles.
1939 The style option for tool boxes is QStyleOptionToolBox. It
1940 contains the text and icon of the tool box contents. The only
1941 state set by QToolBox is \c State_Sunken, which is set when the user
1942 presses a tab down with the mouse. The rest of the
1943 QStyleOptionToolBox members are:
1951 \li The icon on the toolbox tab.
1954 \li The text on the toolbox tab.
1959 The size grip calculates its size hint with \c CT_SizeGrip. The pixel
1960 metric \c PM_SizeGripSize is currently unused by Qt. The element tree
1961 for an image in the Plastique style of QSizeGrip follows:
1963 \image javastyle/sizegrip.png
1965 \image javastyle/sizegripimage.png
1967 We show the size grip in \l{QMainWindow}'s bottom right
1970 The size grip style option, QStyleOptionSizeGrip, has one
1971 member besides the common members from QStyleOption:
1979 \li A Qt::Corner value that describes which corner in a
1980 window (or equivalent) the grip is located.
1983 \section3 Rubber Band
1985 The \l{QRubberBand}'s style tree consists of two nodes.
1987 \image javastyle/rubberband.png
1989 We present an image of a Java style window being moved in a
1990 QMdiArea with a rubber band:
1992 \image javastyle/rubberbandimage.png
1994 The style option for rubber bands is QStyleOptionRubberBand.
2003 \li Boolean that is \c true if the rubber band must be
2004 drawn in an opaque style (i.e., color).
2007 \li A QRubberBand::Shape enum value that holds the
2008 shape of the band (which is either a rectangle or a
2012 \section3 Dock Widgets
2014 When the dock widget lays out its contents it asks the style for
2015 these pixel metrics: \c PM_DockWidgetSeparatorExtent,
2016 \c PM_DockWidgetTitleBarButtonMargin, \c PM_DockWidgetFrameWidth, and
2017 \c PM_DockWidgetTitleMargin. It also calculates the bounding
2018 rectangles of the float and close buttons with
2019 \c SE_DockWidgetCloseButton and \c SE_DockWidgetFloatButton.
2021 \image javastyle/dockwidget.png
2023 The dotted lines indicate that the sender keeps instances of the
2024 recipient of the arrow (i.e., it is not a style element to draw).
2025 The dock widget only draws \c PE_frameDockWidget when it is detached
2026 from its main window (i.e., it is a top level window). If it is
2027 docked it draws the indicator dock widget resize handle. We show a
2028 dock widget in both docked and floating state in the plastique
2031 \image javastyle/dockwidgetimage.png
2033 The style option is QStyleOptionDockWidget:
2041 \li Boolean that holds whether the dock window can be
2045 \li Boolean that holds whether the dock window can
2046 float (i.e., detach from the main window in which
2050 \li Boolean that holds whether the window is movable
2051 (i.e., can move to other dock widget areas).
2054 \li The title text of the dock window.
2057 For the buttons, QStyleOptionButton is used (see \l{Tool Buttons}
2058 for content description). The dock widget resize handle has a